这是一个创建于 2872 天前的主题，其中的信息可能已经有所发展或是发生改变。
api 文档是用 wiki 还是 doc
第 1 条附言 · 2017-02-16 11:08:06 +08:00
除了 api 文档，还有需求设计文档。所以我的问题应该是怎么管理文档的，包括需求文档、设计文档、 api 文档等
第 2 条附言 · 2017-02-16 20:31:13 +08:00
总结如下，后面再补充
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
 |
1
yxzblue 2017-02-16 08:38:17 +08:00
Swagger
|
 |
2
kancloud 2017-02-16 08:43:13 +08:00
用看云 可以支持 api 文档在线调试
|
 |
3
coldmn3 2017-02-16 08:58:04 +08:00
用的 Confluence, 感觉还行吧，同求推荐。
|
 |
4
linkoubian 2017-02-16 09:00:31 +08:00
@coldmn3 同样是 Confluence
|
 |
5
loadsome 2017-02-16 09:03:44 +08:00 via iPhone
小幺鸡
|
 |
6
Felldeadbird 2017-02-16 09:07:19 +08:00
写工具反射得出 API 文档
|
 |
7
jimyan OP @Felldeadbird 我们是先文档，除了 API 文档，还有设计文档等
|
 |
8
liyj144 2017-02-16 09:24:44 +08:00
|
 |
9
daben1990 2017-02-16 09:27:04 +08:00
https://github.com/fyddaben/lettuce 我们用的 API Blueprint 语法，然后起了个 mock server ，
|
 |
10
SourceMan 2017-02-16 09:27:26 +08:00  7
口头传述
|
 |
11
thanksir 2017-02-16 09:27:26 +08:00
推荐 showdoc ，这个还不错的
|
 |
12
chipmuck 2017-02-16 09:28:01 +08:00
通过 gitlab 传 md....
|
 |
13
StevenTong 2017-02-16 09:28:27 +08:00
swagger +1
|
 |
14
lifesimple 2017-02-16 09:29:54 +08:00
swagger +2
|
 |
15
Abigale 2017-02-16 09:31:14 +08:00
没有。
|
 |
16
awolfly9 2017-02-16 09:31:16 +08:00
天啦，还有 API 文档,没听说过
|
 |
17
superpeaser 2017-02-16 09:34:02 +08:00 via iPhone
Confluence +1
|
 |
18
lijinma 2017-02-16 09:35:07 +08:00
raml
|
 |
19
Asan 2017-02-16 09:37:05 +08:00
wiki
|
 |
20
wawehi 2017-02-16 09:37:30 +08:00
gogs 建个项目 传 .md 上去
|
 |
21
liyu001989 2017-02-16 09:38:37 +08:00
apidoc http://apidocjs.com/
|
 |
22
odirus 2017-02-16 09:39:26 +08:00
尝试过很多，不过现在都转入了 doc ，模板建立好之后，还是挺方便的。
|
 |
23
tjxiter 2017-02-16 09:41:58 +08:00
没有 API 文档。。。
|
 |
24
PICKSOMETHING 2017-02-16 09:47:54 +08:00
quip
|
 |
25
mcfog 2017-02-16 09:54:51 +08:00
内嵌在代码中，验证参数和展示文档调用同一个来源
|
 |
26
nashxk 2017-02-16 10:11:45 +08:00
confluence ，有个问题是，后来新增的很多字段，都会忘记更新上去。。而且支持 MarkDown 还需要安装插件好像。。
|
 |
27
solee 2017-02-16 10:15:11 +08:00
apidoc
|
 |
28
amon 2017-02-16 10:39:15 +08:00
markdown+gitlab
|
 |
29
ixiaozhi 2017-02-16 10:40:46 +08:00
意念传输
|
 |
30
wmttom 2017-02-16 10:46:50 +08:00
Swagger +3
代码生成文档，或者文档生成代码，一旦各自独立书写总会产生不一致。 |
 |
32
kaka8wp 2017-02-16 10:56:33 +08:00
swagger+1
|
 |
33
kenshinhu 2017-02-16 10:57:00 +08:00 1
我这边是在用 node 的 apidoc 。。。。。
|
 |
34
xwartz 2017-02-16 10:59:20 +08:00
postman
|
 |
35
settings 2017-02-16 11:01:38 +08:00
Swagger 可以在线调试，根据文档 API 还能反射出静态文档
|
 |
36
lc4t 2017-02-16 11:08:38 +08:00 via iPhone
swagger+quip
|
 |
37
MasterC 2017-02-16 11:10:03 +08:00
有道云协作 + markdown
|
 |
38
zyue 2017-02-16 11:12:37 +08:00 1
使用 wiki 配合 jira 挺好用的
|
 |
39
klgd 2017-02-16 11:22:29 +08:00
|
 |
40
lshero 2017-02-16 11:22:58 +08:00
Confluence 编辑文档浏览器天天卡死
|
 |
41
zhuf 2017-02-16 11:28:56 +08:00
swagger+1
|
 |
42
mckelvin 2017-02-16 11:53:46 +08:00
https://apiblueprint.org/ 用 atom 加插件写类似 Markdown 的语法，用 Aglio 渲染成 html 文档, 顺手用 Drakov 生成 mock server 方便前后端分离开发。
|
 |
44
caixiexin 2017-02-16 12:26:24 +08:00 via Android
用 swagger 可以保持接口跟文档同时更新，但是如果用接口生成文档的方式，源代码会有很多原来放在文档里的说明信息。
不管哪种方式，写文档的工作是省不掉的😂 |
 |
45
firstfire 2017-02-16 12:40:36 +08:00
代码里用 Javadoc
API 文档用 Markdown 写用 SVN 管理版本 |
 |
46
sobigfish 2017-02-16 12:47:47 +08:00
OpenAPI / Swagger
|
 |
47
argon33 2017-02-16 13:02:25 +08:00
文档的维护太难了。。。放在代码库里？
|
 |
49
geeksu 2017-02-16 13:46:28 +08:00
我们的 API 没有文档。。
|
 |
50
AJian 2017-02-16 14:29:14 +08:00
用过 RAP
|
 |
51
Ixizi 2017-02-16 14:39:51 +08:00
目前在用 RAP 虽然不喜欢 java
|
 |
53
loveskyforever 2017-02-16 14:54:50 +08:00
用的是 SBDoc ，可以内网测试， mock 数据，自动生成文档，干净无插件 http://123.57.77.6
|
 |
54
Ypoem 2017-02-16 15:04:02 +08:00
支持下
|
 |
55
yy1300326388 2017-02-16 16:35:38 +08:00
postmant
|
 |
56
zorui 2017-02-16 16:49:24 +08:00
swagger +1
|
|
57
zorui 2017-02-16 16:50:19 +08:00
swagger + asciidoc
|
 |
59
irory 2017-02-16 17:59:50 +08:00
推荐自动生成文档, 比如 PY 的 sphinx ， api 更新方便维护 ，一键生成也方便。
|
 |
60
ivanyin 2017-02-16 18:44:07 +08:00
用 RAP
|
 |
61
codeyung 2017-02-16 19:04:04 +08:00
Confluence
|
 |
62
freestyle 2017-02-16 19:50:09 +08:00 via iPhone
API 的话 Swagger 搭一个本地服务器 然后用 yaml 写文档就行了，自动渲染 高亮
|
 |
64
lgn21st 2017-02-16 20:40:46 +08:00
|
|
65
freestyle 2017-02-16 20:52:58 +08:00
@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
|
 |
67
Monstercat 2017-02-16 21:18:43 +08:00
Github Private Repo 放 MD...
|
 |
68
lzjamao 2017-02-16 21:23:23 +08:00
无
|
 |
69
abirdcanfly 2017-02-16 22:42:01 +08:00
我是业务部门的, 对接的 IT 部门每用一次 API 让我们在对接门户导一次 <<<吐槽
|
 |
70
langjiyuan 2017-02-16 22:55:42 +08:00
意念传输 2333
|
 |
71
IgniteWhite 2017-02-16 23:14:18 +08:00
楼主附言的背后应该是一张面无表情的脸
|
 |
73
cxbig 2017-02-17 02:00:55 +08:00
公司用 Atlassian 的产品
所以需求和设计文档一般都是 Confluence 做描述， PSD 类设计文件用 Google Drive 共享。 关于 API 文档，如 PHP 项目：公司要求每个 attribute 和 method 必须写清楚 PHP Doc ，大家都用 PhpStorm ，一个类有什么东西、怎么用一目了然。 |
 |
74
msg7086 2017-02-17 03:34:55 +08:00
意念传输，这个总结得很好……
|
 |
75
whalegia 2017-02-17 05:25:27 +08:00
OneNote + Swagger
|
 |
76
rashawn 2017-02-17 06:43:37 +08:00 via iPhone
通过代码生成 缺点是代码里注释有点多…
|
 |
77
Cbdy 2017-02-17 07:43:51 +08:00 via Android
根据代码注释生成文档（ javadoc ）+ 根据 api 接口使用 springfox 的工具生成 adoc
只要写好代码，文档都是自动生成的 |
 |
78
winglight2016 2017-02-17 09:25:52 +08:00
意念传输——就服这个，能传授吗？
|
 |
79
juice 2017-02-17 09:29:46 +08:00
postman ， swagger
|
 |
80
Yuansir 2017-02-17 09:30:06 +08:00
居然没有 gitbook
|
 |
81
zhangliang605 2017-02-17 09:54:55 +08:00
Confluence 。
是我们是一个 1200+人的团队，面临开发，测试，产品经理，项目经理，运营，商务等等各个部门的协作。 Confluence 能跟公司的通信录系统，邮箱系统对接。当关注的文档发生变化时，立即发送邮件给相关同事。同时， Confluence 支持各种插件，富文本编辑，代码高亮，评论，备注等等功能一应俱全。 |
 |
82
antowa 2017-02-17 10:20:02 +08:00
我司使用意念传输。精神授权。
|
|
83
settings 2017-02-17 11:42:09 +08:00
@klgd 默认不支持，可以反射 markdown ，我们是用 swagger api 反射 markdown ，再把 markdown 提交 git ，通过 gollum 展示 wiki 。
生成 markdown 的脚本： https://github.com/ZhangBohan/swagger_to_markdown |
 |
84
keepcleargas 2017-02-17 11:45:38 +08:00
slate + git
|
 |
85
wjh3936 2017-02-17 12:31:09 +08:00
文档？看代码 [冷漠脸]
|
 |
86
sumuu 2017-02-17 12:59:47 +08:00
Swagger + Google Drive
|
 |
88
billyu 2017-02-17 13:35:58 +08:00
我用的 EasyAPI
|
 |
89
caotian 2017-02-17 15:36:32 +08:00
|
 |
91
Hypn0s 2017-02-17 17:14:04 +08:00
Confluence+1
|
 |
92
flowerwrong 2017-02-17 17:15:10 +08:00 via iPhone
口口想传
|
 |
93
sampeng 2017-02-17 19:48:17 +08:00
api 是什么东西？可以吃吗？
|
 |
94
airingursb 2017-02-19 14:01:53 +08:00 via iPhone
rap
|
 |
95
962680038 2017-02-20 10:00:42 +08:00
SBDoc 不错啊，楼主可以去了解下，操作很简洁，效果很好，链接： http://123.57.77.6/
|
 |
96
dozer47528 2017-02-20 10:48:44 +08:00
想不收费自己搭建的话，可以使用 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 可以配置邮箱白名单，这样只有你们公司的人能访问了。 |
 |
97
HowToMakeLove 2017-02-20 21:43:04 +08:00
apidoc
|
 |
98
jsq2627 2017-03-09 13:04:34 +08:00
|
 |
99
yuhanle 2017-03-21 14:11:19 +08:00
先开大会，再开小会，最后一对一，手把手同步需求
|
 |
100
HuntBao 2017-09-28 11:48:20 +08:00
可以试试 NEI 接口管理平台： https://nei.netease.com
|
Select Language