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

[jimyan]

api   文档是用 wiki 还是 doc

除了 api 文档，还有需求设计文档。所以我的问题应该是怎么管理文档的，包括需求文档、设计文档、 api 文档等

总结如下，后面再补充
Swagger
Confluence
showdoc
口头传述
gitlab 传 md....
天啦，还有 API 文档,没听说过
raml
wiki
gogs
apidoc
quip
意念传输
postman
RAP

[yxzblue]

Swagger

[kancloud]

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

[coldmn3]

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

[linkoubian]

@coldmn3 同样是 Confluence

[loadsome]

小幺鸡

[Felldeadbird]

写工具反射得出 API 文档

[jimyan]

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

[liyj144]

参考： https://www.v2ex.com/t/309716#reply9

[daben1990]

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

[SourceMan]

口头传述

[thanksir]

推荐 showdoc ，这个还不错的

[chipmuck]

通过 gitlab 传 md....

[StevenTong]

swagger +1

[lifesimple]

swagger +2

[Abigale]

没有。

[awolfly9]

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

[superpeaser]

Confluence +1

[lijinma]

raml

[Asan]

wiki

[wawehi]

gogs 建个项目 传 .md 上去

[liyu001989]

apidoc http://apidocjs.com/

[odirus]

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

[tjxiter]

没有 API 文档。。。

[PICKSOMETHING]

quip

[mcfog]

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

[nashxk]

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

[solee]

apidoc

[amon]

markdown+gitlab

[ixiaozhi]

意念传输

[wmttom]

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

[jimyan]

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

[kaka8wp]

swagger+1

[kenshinhu]

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

[xwartz]

postman

[settings]

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

[lc4t]

swagger+quip

[MasterC]

有道云协作 + markdown

[zyue]

使用 wiki 配合 jira 挺好用的

[klgd]

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

[lshero]

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

[zhuf]

swagger+1

[mckelvin]

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

[kankana]

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

[caixiexin]

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

[firstfire]

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

[sobigfish]

OpenAPI / Swagger

[argon33]

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

[settings]

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

[geeksu]

我们的 API 没有文档。。

[AJian]

用过 RAP

[Ixizi]

目前在用 RAP 虽然不喜欢 java

[Jackeriss]

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

[loveskyforever]

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

[Ypoem]

支持下

[yy1300326388]

postmant

[zorui]

swagger +1

[zorui]

swagger + asciidoc

[v4ex4b]

@SourceMan \(≧▽≦)/

[irory]

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

[ivanyin]

用 RAP

[codeyung]

Confluence

[freestyle]

API 的话 Swagger 搭一个本地服务器 然后用 yaml 写文档就行了，自动渲染 高亮

[jimyan]

@freestyle 这个只能是 java 吗

[lgn21st]

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

[freestyle]

@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

[klgd]

@settings 嗯 是的 可以对比吗？

[Monstercat]

Github Private Repo 放 MD...

[lzjamao]

无

[abirdcanfly]

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

[langjiyuan]

意念传输 2333

[IgniteWhite]

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

[romennts]

@kancloud 我在用看云 Hhhh

[cxbig]

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

[msg7086]

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

[whalegia]

OneNote + Swagger

[rashawn]

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

[Cbdy]

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

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

[winglight2016]

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

[juice]

postman ， swagger

[Yuansir]

居然没有 gitbook

[zhangliang605]

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

[antowa]

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

[settings]

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

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

[keepcleargas]

slate + git

[wjh3936]

文档？看代码 [冷漠脸]

[sumuu]

Swagger + Google Drive

[klgd]

@settings 呃~
要这么麻烦哦

[billyu]

我用的 EasyAPI

[caotian]

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

[settings]

@klgd 恩，是的 :D

[Hypn0s]

Confluence+1

[flowerwrong]

口口想传

[sampeng]

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

[airingursb]

rap

[962680038]

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

[dozer47528]

想不收费自己搭建的话，可以使用 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

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

[HowToMakeLove]

apidoc

[jsq2627]

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

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

[yuhanle]

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

[HuntBao]

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