大家都用什么写 api 文档？

V2EX = way to explore

V2EX 是一个关于分享和探索的地方

现在注册

已注册用户请登录

V2EX 提问指南

这是一个创建于 3700 天前的主题，其中的信息可能已经有所发展或是发生改变。

列出所有api，每个api需要的参数列表、参数类型、是否必填、参数说明。
每个api的返回值。

参数

API

列出

21 条回复 • 2014-09-20 16:06:09 +08:00

lizhijun

2014-09-19 10:39:17 +08:00

markdown？

yibin001

2014-09-19 10:44:14 +08:00

@lizhijun
但是要用表格来写参数列表，比较头疼。。

linnchord

2014-09-19 10:44:18 +08:00

wiki by markdown

cnxh

2014-09-19 10:49:16 +08:00

haroopad

tolbkni

2014-09-19 10:59:47 +08:00

@yibin001 Markdown + GFM

jamiesun

2014-09-19 11:02:19 +08:00

不用sphinx吗

lululau

2014-09-19 11:06:55 +08:00

http://apiary.io

TangMonk

2014-09-19 11:10:03 +08:00

bitbucket 的 wiki

FuryBean

2014-09-19 11:11:30 +08:00

YuiDoc应该满足楼主的需求。YuiDoc实际上是不限制语言的，而且也不需要写到源码里面。

TangMonk

2014-09-19 11:12:11 +08:00

上次做的一个外包, 大家瞟下文档, 有没得啥子可提高的:

https://bitbucket.org/wuao/daxuebao-api/wiki/Home

davepkxxx

2014-09-19 11:12:25 +08:00

javadoc

yibin001

2014-09-19 11:29:57 +08:00

@lululau
这个不错。

yibin001

2014-09-19 11:32:38 +08:00

@lululau 语法也挺蛋疼的。。

lincanbin

2014-09-19 11:56:27 +08:00

markdown

konakona

2014-09-19 12:23:46 +08:00

哎...只能用excel、word写，用wiki除了我以外没人愿意维护，因为不愿意学wiki的写法...TAT

shiny

2014-09-19 12:25:03 +08:00

javadoc / phpdoc 这类语法,自动导出下就行了.

hehuozhao

2014-09-19 12:35:32 +08:00

https://readthedocs.org/

zeayes

2014-09-19 12:49:49 +08:00

trac wiki

Winny

2014-09-19 16:59:25 +08:00 via iPad

ASP.Net的Web api框架自动生成

xylophone21

2014-09-19 20:42:42 +08:00

这个要看语言吧，
c用doxygen
java用javadoc
JS只用NP API做过扩展，没找到太好的方案，现在感觉自定义注释+脚本+latex不错，不过没实施过。

总之，个人的感觉是接口文档不写在代码里就等于没写，根本没人看，同步也非常麻烦。

猿类都懒

pantaovay

2014-09-20 16:06:09 +08:00

markdown 使用 api blueprint生成很酷炫