你们团队都是怎么管理 API 文档的

Swagger

用看云 可以支持 api 文档在线调试

用的 Confluence, 感觉还行吧，同求推荐。

@coldmn3 同样是 Confluence

小幺鸡

写工具反射得出 API 文档

@Felldeadbird 我们是先文档，除了 API 文档，还有设计文档等

参考： t/309716#reply9

https://github.com/fyddaben/lettuce 我们用的 API Blueprint 语法，然后起了个 mock server ，

口头传述

推荐 showdoc ，这个还不错的

通过 gitlab 传 md....

swagger +1

swagger +2

没有。

天啦，还有 API 文档,没听说过

Confluence +1

raml

wiki

gogs 建个项目 传 .md 上去

apidoc http://apidocjs.com/

尝试过很多，不过现在都转入了 doc ，模板建立好之后，还是挺方便的。

没有 API 文档。。。

quip

内嵌在代码中，验证参数和展示文档调用同一个来源

confluence ，有个问题是，后来新增的很多字段，都会忘记更新上去。。而且支持 MarkDown 还需要安装插件好像。。

apidoc

markdown+gitlab

意念传输

Swagger +3
代码生成文档，或者文档生成代码，一旦各自独立书写总会产生不一致。

@odirus doc 多人编辑和同步很麻烦。当然谷歌 doc 是可以的

swagger+1

我这边是在用 node 的 apidoc 。。。。。

postman

Swagger 可以在线调试，根据文档 API 还能反射出静态文档

swagger+quip

有道云协作 + markdown

使用 wiki 配合 jira 挺好用的

@yxzblue
@StevenTong
@lifesimple
@wmttom
@kaka8wp
@settings
@lc4t
请教一下， swagger 有版本间的比较吗？

Confluence 编辑文档浏览器天天卡死

swagger+1

https://apiblueprint.org/ 用 atom 加插件写类似 Markdown 的语法，用 Aglio 渲染成 html 文档, 顺手用 Drakov 生成 mock server 方便前后端分离开发。

apizza.cc 用的是这个。 postman 后直接文档

用 swagger 可以保持接口跟文档同时更新，但是如果用接口生成文档的方式，源代码会有很多原来放在文档里的说明信息。
不管哪种方式，写文档的工作是省不掉的

代码里用 Javadoc
API 文档用 Markdown 写用 SVN 管理版本

文档的维护太难了。。。放在代码库里？

@klgd 版本间的比较指的是文档更新后的对比吗？

我们的 API 没有文档。。

用过 RAP

目前在用 RAP 虽然不喜欢 java

@ixiaozhi 神圣的 F2 连着我们的思想

用的是 SBDoc ，可以内网测试， mock 数据，自动生成文档，干净无插件 http://123.57.77.6

支持下

postmant

swagger +1

swagger + asciidoc

@SourceMan \()/

推荐自动生成文档, 比如 PY 的 sphinx ， api 更新方便维护 ，一键生成也方便。

用 RAP

Confluence

@freestyle 这个只能是 java 吗

居然没有 https://github.com/lord/slate

@jimyan 任何语言 API 是 json 构建的就行 官网:http://swagger.io/swagger-ui/ github:https://github.com/swagger-api/swagger-ui clone 下来, 随便搞个简单 http 服务器, dist 目录作为作为 root 目录就可以跑起来 也可以后面小修改下加登录才能查看 语法规范在这里 https://github.com/OAI/OpenAPI-Specification/blob/master/versions/2.0.md

@settings 嗯 是的 可以对比吗？

Github Private Repo 放 MD...

无

我是业务部门的, 对接的 IT 部门每用一次 API 让我们在对接门户导一次 <<<吐槽

意念传输 2333

楼主附言的背后应该是一张面无表情的脸

@kancloud 我在用看云 Hhhh

公司用 Atlassian 的产品
所以需求和设计文档一般都是 Confluence 做描述， PSD 类设计文件用 Google Drive 共享。
关于 API 文档，如 PHP 项目：公司要求每个 attribute 和 method 必须写清楚 PHP Doc ，大家都用 PhpStorm ，一个类有什么东西、怎么用一目了然。

意念传输，这个总结得很好……

OneNote + Swagger

通过代码生成 缺点是代码里注释有点多…

根据代码注释生成文档（ javadoc ）+ 根据 api 接口使用 springfox 的工具生成 adoc

只要写好代码，文档都是自动生成的

意念传输就服这个，能传授吗？

postman ， swagger

居然没有 gitbook

Confluence 。
是我们是一个 1200+人的团队，面临开发，测试，产品经理，项目经理，运营，商务等等各个部门的协作。 Confluence 能跟公司的通信录系统，邮箱系统对接。当关注的文档发生变化时，立即发送邮件给相关同事。同时， Confluence 支持各种插件，富文本编辑，代码高亮，评论，备注等等功能一应俱全。

我司使用意念传输。精神授权。

@klgd 默认不支持，可以反射 markdown ，我们是用 swagger api 反射 markdown ，再把 markdown 提交 git ，通过 gollum 展示 wiki 。

生成 markdown 的脚本： https://github.com/ZhangBohan/swagger_to_markdown

slate + git

文档？看代码 [冷漠脸]

Swagger + Google Drive

@settings 呃~
要这么麻烦哦

我用的 EasyAPI

用的 http://daux.io/，还不错

@klgd 恩，是的 :D

Confluence+1

口口想传

api 是什么东西？可以吃吗？

rap

SBDoc 不错啊，楼主可以去了解下，操作很简洁，效果很好，链接： http://123.57.77.6/

想不收费自己搭建的话，可以使用 https://apiblueprint.org/
它本身提供云服务，但也可以自己搭建。写文档就是写 markdown ， github 也认这种格式。





然后开源社区已经做好了各种工具，包括把 apiblueprint 格式生成 html ， apiblueprint 生成 mock server 等等，非常方便。
我做了个 docker 镜像，只要提供你们写文档的 git 仓库，就可以一键搭建。包含文档服务器， mock server 和 hook api （文档更新的时候自动更新相关内容）
https://github.com/dozer47528/api-blueprint-docker

另外，你可能会需要对静态网站做 oauth2 认证功能，可以利用这个东西： https://github.com/bitly/oauth2_proxy

可以配置邮箱白名单，这样只有你们公司的人能访问了。

apidoc

个人觉得从测试用例生成文档是体验最棒的文档开发方式。

最近给 node.js 做的轮子，强力推荐一下
https://github.com/stackia/test2doc.js

先开大会，再开小会，最后一对一，手把手同步需求

可以试试 NEI 接口管理平台： https://nei.netease.com