api 文档是用 wiki 还是 doc
• 请不要在回答技术问题时复制粘贴 AI 生成的内容
This topic created in 3549 days ago, the information mentioned may be changed or developed.
Supplement 1 · Feb 16, 2017
除了 api 文档，还有需求设计文档。所以我的问题应该是怎么管理文档的，包括需求文档、设计文档、 api 文档等
Supplement 2 · Feb 16, 2017
总结如下，后面再补充
Swagger
Confluence
showdoc
口头传述
gitlab 传 md....
天啦，还有 API 文档,没听说过
raml
wiki
gogs
apidoc
quip
意念传输
postman
RAP
Swagger
Confluence
showdoc
口头传述
gitlab 传 md....
天啦，还有 API 文档,没听说过
raml
wiki
gogs
apidoc
quip
意念传输
postman
RAP
 |
yxzblueFeb 16, 2017
1
Swagger
|
 |
kancloudFeb 16, 2017
2
用看云 可以支持 api 文档在线调试
|
 |
coldmn3Feb 16, 2017
3
用的 Confluence, 感觉还行吧，同求推荐。
|
 |
linkoubianFeb 16, 2017
4
@coldmn3 同样是 Confluence
|
 |
loadsomeFeb 16, 2017 via iPhone
5
小幺鸡
|
 |
FelldeadbirdFeb 16, 2017
6
写工具反射得出 API 文档
|
 |
7
@Felldeadbird 我们是先文档，除了 API 文档，还有设计文档等
|
 |
liyj144Feb 16, 2017
8
|
 |
daben1990Feb 16, 2017
9
https://github.com/fyddaben/lettuce 我们用的 API Blueprint 语法，然后起了个 mock server ，
|
 |
10
口头传述
|
7 |
thanksirFeb 16, 2017
11
推荐 showdoc ，这个还不错的
|
 |
chipmuckFeb 16, 2017
12
通过 gitlab 传 md....
|
 |
StevenTongFeb 16, 2017
13
swagger +1
|
 |
lifesimpleFeb 16, 2017
14
swagger +2
|
 |
AbigaleFeb 16, 2017
15
没有。
|
 |
awolfly9Feb 16, 2017
16
天啦，还有 API 文档,没听说过
|
 |
superpeaserFeb 16, 2017 via iPhone
17
Confluence +1
|
 |
lijinmaFeb 16, 2017
18
raml
|
 |
elepantFeb 16, 2017
19
wiki
|
 |
wawehiFeb 16, 2017
20
gogs 建个项目 传 .md 上去
|
 |
liyu001989Feb 16, 2017
21
apidoc http://apidocjs.com/
|
 |
odirusFeb 16, 2017
22
尝试过很多，不过现在都转入了 doc ，模板建立好之后，还是挺方便的。
|
 |
tjxiterFeb 16, 2017
23
没有 API 文档。。。
|
 |
PICKSOMETHINGFeb 16, 2017
24
quip
|
 |
mcfogFeb 16, 2017
25
内嵌在代码中，验证参数和展示文档调用同一个来源
|
 |
nashxkFeb 16, 2017
26
confluence ，有个问题是，后来新增的很多字段，都会忘记更新上去。。而且支持 MarkDown 还需要安装插件好像。。
|
 |
soleeFeb 16, 2017
27
apidoc
|
 |
amonFeb 16, 2017
28
markdown+gitlab
|
 |
ixiaozhiFeb 16, 2017
29
意念传输
|
 |
wmttomFeb 16, 2017
30
Swagger +3
代码生成文档，或者文档生成代码，一旦各自独立书写总会产生不一致。 |
 |
kaka8wpFeb 16, 2017
32
swagger+1
|
 |
33
我这边是在用 node 的 apidoc 。。。。。
|
 |
xwartzFeb 16, 2017
34
postman
|
 |
settingsFeb 16, 2017
35
Swagger 可以在线调试，根据文档 API 还能反射出静态文档
|
 |
lc4tFeb 16, 2017 via iPhone
36
swagger+quip
|
 |
MasterCFeb 16, 2017
37
有道云协作 + markdown
|
 |
38
使用 wiki 配合 jira 挺好用的
|
 |
klgdFeb 16, 2017
39
|
 |
lsheroFeb 16, 2017
40
Confluence 编辑文档浏览器天天卡死
|
 |
zhufFeb 16, 2017
41
swagger+1
|
 |
mckelvinFeb 16, 2017
42
https://apiblueprint.org/ 用 atom 加插件写类似 Markdown 的语法，用 Aglio 渲染成 html 文档, 顺手用 Drakov 生成 mock server 方便前后端分离开发。
|
 |
caixiexinFeb 16, 2017 via Android
44
用 swagger 可以保持接口跟文档同时更新，但是如果用接口生成文档的方式，源代码会有很多原来放在文档里的说明信息。
不管哪种方式，写文档的工作是省不掉的😂 |
 |
firstfireFeb 16, 2017
45
代码里用 Javadoc
API 文档用 Markdown 写用 SVN 管理版本 |
 |
run2Feb 16, 2017
46
OpenAPI / Swagger
|
 |
argon33Feb 16, 2017
47
文档的维护太难了。。。放在代码库里？
|
 |
geeksuFeb 16, 2017
49
我们的 API 没有文档。。
|
 |
AJianFeb 16, 2017
50
用过 RAP
|
 |
IxiziFeb 16, 2017
51
目前在用 RAP 虽然不喜欢 java
|
 |
loveskyforeverFeb 16, 2017
53
用的是 SBDoc ，可以内网测试， mock 数据，自动生成文档，干净无插件 http://123.57.77.6
|
 |
YpoemFeb 16, 2017
54
支持下
|
 |
yy1300326388Feb 16, 2017
55
postmant
|
 |
zoruiFeb 16, 2017
56
swagger +1
|
|
zoruiFeb 16, 2017
57
swagger + asciidoc
|
 |
iroryFeb 16, 2017
59
推荐自动生成文档, 比如 PY 的 sphinx ， api 更新方便维护 ，一键生成也方便。
|
 |
ivanyinFeb 16, 2017
60
用 RAP
|
 |
codeyungFeb 16, 2017
61
Confluence
|
 |
freestyleFeb 16, 2017 via iPhone
62
API 的话 Swagger 搭一个本地服务器 然后用 yaml 写文档就行了，自动渲染 高亮
|
 |
lgn21stFeb 16, 2017
64
|
|
freestyleFeb 16, 2017
65
@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
|
 |
MonstercatFeb 16, 2017
67
Github Private Repo 放 MD...
|
 |
lzjamaoFeb 16, 2017
68
无
|
 |
abirdcanflyFeb 16, 2017
69
我是业务部门的, 对接的 IT 部门每用一次 API 让我们在对接门户导一次 <<<吐槽
|
 |
langjiyuanFeb 16, 2017
70
意念传输 2333
|
 |
FurN1Feb 16, 2017
71
楼主附言的背后应该是一张面无表情的脸
|
 |
cxbigFeb 17, 2017
73
公司用 Atlassian 的产品
所以需求和设计文档一般都是 Confluence 做描述， PSD 类设计文件用 Google Drive 共享。 关于 API 文档，如 PHP 项目：公司要求每个 attribute 和 method 必须写清楚 PHP Doc ，大家都用 PhpStorm ，一个类有什么东西、怎么用一目了然。 |
 |
msg7086Feb 17, 2017
74
意念传输，这个总结得很好……
|
 |
whalegiaFeb 17, 2017
75
OneNote + Swagger
|
 |
rashawnFeb 17, 2017 via iPhone
76
通过代码生成 缺点是代码里注释有点多…
|
 |
CbdyFeb 17, 2017 via Android
77
根据代码注释生成文档（ javadoc ）+ 根据 api 接口使用 springfox 的工具生成 adoc
只要写好代码，文档都是自动生成的 |
 |
winglight2016Feb 17, 2017
78
意念传输——就服这个，能传授吗？
|
 |
juiceFeb 17, 2017
79
postman ， swagger
|
 |
YuansirFeb 17, 2017
80
居然没有 gitbook
|
 |
zhangliang605Feb 17, 2017
81
Confluence 。
是我们是一个 1200+人的团队，面临开发，测试，产品经理，项目经理，运营，商务等等各个部门的协作。 Confluence 能跟公司的通信录系统，邮箱系统对接。当关注的文档发生变化时，立即发送邮件给相关同事。同时， Confluence 支持各种插件，富文本编辑，代码高亮，评论，备注等等功能一应俱全。 |
 |
antowaFeb 17, 2017
82
我司使用意念传输。精神授权。
|
|
settingsFeb 17, 2017
83
@klgd 默认不支持，可以反射 markdown ，我们是用 swagger api 反射 markdown ，再把 markdown 提交 git ，通过 gollum 展示 wiki 。
生成 markdown 的脚本： https://github.com/ZhangBohan/swagger_to_markdown |
 |
keepcleargasFeb 17, 2017
84
slate + git
|
 |
wjh3936Feb 17, 2017
85
文档？看代码 [冷漠脸]
|
 |
sumuuFeb 17, 2017
86
Swagger + Google Drive
|
 |
billyuFeb 17, 2017
88
我用的 EasyAPI
|
 |
caotianFeb 17, 2017
89
|
 |
Hypn0sFeb 17, 2017
91
Confluence+1
|
 |
flowerwrongFeb 17, 2017 via iPhone
92
口口想传
|
 |
sampengFeb 17, 2017
93
api 是什么东西？可以吃吗？
|
 |
airingursbFeb 19, 2017 via iPhone
94
rap
|
 |
962680038Feb 20, 2017
95
SBDoc 不错啊，楼主可以去了解下，操作很简洁，效果很好，链接： http://123.57.77.6/
|
 |
dozer47528Feb 20, 2017
96
想不收费自己搭建的话，可以使用 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 可以配置邮箱白名单，这样只有你们公司的人能访问了。 |
 |
HowToMakeLoveFeb 20, 2017
97
apidoc
|
 |
98
|
 |
yuhanleMar 21, 2017
99
先开大会，再开小会，最后一对一，手把手同步需求
|
 |
HuntBaoSep 28, 2017
100
可以试试 NEI 接口管理平台： https://nei.netease.com
|
Select Language