各位服务端程序员一般用什么工具写 api 文档给客户端看？

V2EX = way to explore

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

现在注册

已注册用户请登录

V2EX 提问指南

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

我目前拿到的 api 文档大部分都是 word

API

文档

程序员

word

21 条回复 • 2016-05-10 10:06:18 +08:00

silencewwt

2016-05-03 01:18:15 +08:00

Sphinx, 然后生成 `read the docs` 风格的 html

ewBuyVmLZMZE

2016-05-03 01:44:34 +08:00

是时候安利 swagger 了

Victor215

2016-05-03 07:55:53 +08:00 via Android

我们用 markdown

crysislinux

2016-05-03 08:33:10 +08:00

raml ， execl 也比 word 要好吧，其实我觉得 execl 也还可以。。。

lecher

2016-05-03 08:48:57 +08:00 via Android

偷懒的时候直接写个接口专门扫文件，然后输出注释就显示，这样给前端一个 Web 接口就可以看所有注释了。
好处是只需要维护一份文档，方便实时更新，把注释写好就行，坏处太多列不完，文档不规范，没有格式等等一堆工程化要求没有达到

yellowV2ex

2016-05-03 09:01:33 +08:00

我最近用了一个牛逼的东西，然后报价可以多报个一两千，这就是逼格的价值。

用 aglio 生成文档 https://github.com/danielgtaylor/aglio ，原始格式是基于 markdown 的 API Blueprint https://apiblueprint.org/

生出来的东西大概是这样子的： http://htmlpreview.github.io/?https://raw.githubusercontent.com/danielgtaylor/aglio/blob/master/examples/default.html
以及三列版 http://htmlpreview.github.io/?https://raw.githubusercontent.com/danielgtaylor/aglio/blob/master/examples/default-triple.html

pepsin

2016-05-03 09:32:12 +08:00

Paw 改改 JS 生成的也不错

odirus

2016-05-03 09:35:54 +08:00

表示强烈关注

fwrq41251

2016-05-03 09:46:28 +08:00

推荐 miredot,个人觉得比 swaggeer 好用。

chinajik

2016-05-03 09:49:11 +08:00

@fwrq41251 要付费~ 然而感觉不错~~

chinajik

2016-05-03 09:50:15 +08:00

@fwrq41251
:)

Always free for non-commercial open source projects.

gucheen

2016-05-03 09:56:41 +08:00

swagger 和 markdown 搭配

Drifter

2016-05-03 10:02:34 +08:00

1 ，做过接口扫描+接口注释输出。

优点是只用维护一份文档；
缺点是页面比较简单，不好定制；

2 ，现在使用的 pelican+某个主题
优点是生成快，不用管文档结构，只写文档；
缺点是主题不好找，不好作内部链接引用。

想尝试用 sphinx+read the doc ，但是 rst 的复杂写法让我望而却步了。