遇到一个尴尬的问题,我司 API 文档都是使用 markdown 来写的,然而是放在项目目录下面的 README.md 中,但是多人人多的时候修改起来就比较麻烦,就想用有没有一种在线的 API 文档管理程序撒的,石墨固然好,好像不支持 Markdown 所以没打算用。
哎。 Fuck
看了各位的评论,表示API文档还是可以独立部署代表比较好,我可不想把自己程序的API说明丢在别人家。
其次,看了下swagger
,感觉UI挺不错,抽时间研究下。
我司下载就是放在仓库下面的README.md中。
1
xuanyan 2017-04-13 10:30:53 +08:00
我们用的 mediawiki 搭建的 api 接口词条
|
2
lawmil 2017-04-13 10:39:17 +08:00 1
既然是 md 写的,推荐个系统 docsify 很方便,样式默认 vue 也可以改其他
|
5
hekunhotmail 2017-04-13 10:43:05 +08:00
wiki 不谢
|
6
zi 2017-04-13 10:46:58 +08:00
我司用 word 。。真的要哭出声来
|
7
AlisaDestiny 2017-04-13 10:52:58 +08:00
|
9
ansheng OP @AlisaDestiny 贵了点,哈哈。
|
10
domty 2017-04-13 11:13:29 +08:00
confluence
|
11
tpsxiong 2017-04-13 11:15:41 +08:00
|
12
linoder 2017-04-13 12:24:46 +08:00
swagger
|
13
flyingghost 2017-04-13 12:35:43 +08:00
www.xiaoyaoji.com
可内网部署 |
14
h4x3rotab 2017-04-13 12:47:55 +08:00
Google 是和源码目录放在一起的 md 文件,同样加入版本管理,代码审查。然后再搭配一个搜索。
|
15
lusyoe 2017-04-13 13:08:45 +08:00 via iPhone
swagger +1
|
16
crossoverJie 2017-04-13 13:22:00 +08:00
有 doc 和 wiki
|
17
tkisme 2017-04-13 13:22:46 +08:00
swagger +1
|
18
nashxk 2017-04-13 13:36:07 +08:00
confluence 。不过没用 markdown ,而且改版的时候更新也不是很及时。。
|
19
ansheng OP @flyingghost 表示打不开,就是需要内网部署的。
|
21
ansheng OP |
22
kooze 2017-04-13 14:10:41 +08:00 4
口耳相传
|
23
zhuf 2017-04-13 14:11:36 +08:00
apidoc
|
25
snriud 2017-04-13 14:36:41 +08:00
最开始是写在 wiki 里,认认真真,完完整整,慢慢地就不维护了,有人要接口文档的话就用 postman 请求一次,截图发给谁。。。
|
27
wudanyang 2017-04-13 14:51:00 +08:00
wiki, 不会调格式
|
28
gengqiupeng 2017-04-13 14:54:18 +08:00
小幺鸡在线文档。不过不是用 markdown 写的
|
29
kaka8wp 2017-04-13 15:06:39 +08:00
有部分文档但基本上不是最新的,最新的也是靠口耳相传
|
30
ivvei 2017-04-13 15:12:31 +08:00
没有文档。自己翻代码
|
31
izoabr 2017-04-13 15:18:04 +08:00
口口相传
|
32
huigeer 2017-04-13 15:24:25 +08:00
apidoc + 1
|
33
ArthurKing 2017-04-13 15:26:06 +08:00
swagger +1
|
34
huigeer 2017-04-13 15:27:06 +08:00
更正: ShowDoc
|
35
qiu0130 2017-04-13 15:38:56 +08:00 via Android
难道没有用 tower 的?
|
36
klgd 2017-04-13 15:45:12 +08:00
showdoc + apidoc
showdoc 是前人用的, coding+编辑维护不是方便,后来用 apidoc ,注释直接写在 code 里,然后命令生成,虽然注释在编写时也不是太方便,但感觉对 coding 和维护好一点儿 |
37
orderc 2017-04-13 16:08:00 +08:00
gitbook
|
40
freezhan 2017-04-13 16:19:46 +08:00
swagger+1
|
41
strongcoder 2017-04-13 16:30:46 +08:00
我司用 word 。。快被气死
|
42
Observer42 2017-04-13 16:38:03 +08:00
swagger
|
44
subdued 2017-04-13 16:42:07 +08:00 4
我司 API 文档靠口口相传
|
45
guodont 2017-04-13 16:46:31 +08:00
swagger +1
apidoc +1 |
46
virusdefender 2017-04-13 16:50:57 +08:00 1
口口相传
心有灵犀 |
47
xxdd 2017-04-13 16:56:46 +08:00
口口相传
心有灵犀 (●'◡'●)ノ♥ |
48
prasanta 2017-04-13 17:02:46 +08:00
用 mkdocs+git
|
49
Ouyangan 2017-04-13 17:17:10 +08:00
swagger+1
|
50
qdpoboy 2017-04-13 17:36:00 +08:00
喊!呀
|
52
Vvfan 2017-04-13 17:37:11 +08:00
看来不止我们用 word /(ㄒoㄒ)/~~
|
53
kisnows 2017-04-13 17:54:17 +08:00
Word Wiki 有道云 + 口口相传
|
54
nextbox 2017-04-13 17:56:12 +08:00
RAP
|
55
imherer 2017-04-13 18:22:43 +08:00
|
56
ydq419453527 2017-04-13 18:29:33 +08:00
|
57
Blazings 2017-04-13 18:30:13 +08:00 via Android
口口相传牛逼
|
58
auhah 2017-04-13 18:31:49 +08:00
想起了前前前公司,我刚工作的时候
CTO 特别屌 自己撸了一套 API 网站 还以为是 IT 公司标配 后来几个公司 tmd 全是 word |
59
mfu 2017-04-13 18:32:03 +08:00
写 WORD 里扔 SVN 上。 T_T
|
60
WhoMercy 2017-04-13 18:43:24 +08:00 via Android
遇到过 word 生成 html 扔内网服务器,给个固定网址的……
|
61
nameldk 2017-04-13 19:53:28 +08:00
文档是写在代码里,然后有专门处理程序会把代码的文档提取出来,生成 api 文档,同时生成测试工具:)
|
62
a412739861 2017-04-13 20:04:35 +08:00
@kooze #22 还不错了,我们是代码讲那过去的故事……
|
63
zhleonix 2017-04-13 20:09:19 +08:00
用 Swagger 或者 RAML 写 YAML 规范,自动产生文档和代码。
|
64
xieweizhi007 2017-04-13 21:53:05 +08:00 via iPhone
apiary
|
65
xieweizhi007 2017-04-13 21:53:37 +08:00 via iPhone
更正: apiary
|
66
G900 2017-04-13 22:02:52 +08:00
GitLab ,和代码分开,做一个单独的 doc 库,用 markdown 写,管理方便
|
68
orvice 2017-04-13 22:50:07 +08:00
swagger :)
|
69
xu1ming 2017-04-13 22:53:11 +08:00 via iPhone 1
我司 google doc
|
70
mingyun 2017-04-13 23:10:52 +08:00
dokuwiki
|
71
loveuqian 2017-04-13 23:36:45 +08:00 via iPhone
就一条 curl 命令
|
72
Jakesoft 2017-04-14 00:50:49 +08:00
竟然没有 sphinx ,专业文档编写 100 年
|
73
zzyzxd 2017-04-14 07:44:49 +08:00
前公司是把 git 目录 mount 到一个 MkDocs 的 container 里……
|
74
jwangkun 2017-04-14 07:46:05 +08:00 via Android
没人推荐小幺鸡么?
|
75
yalanaika 2017-04-14 08:03:36 +08:00
html - chm
|
76
libook 2017-04-14 08:06:07 +08:00
个人觉得 API 文档维护的最大问题是忘记维护,或者有时候赶时间就懒得维护,所以个人倾向于将 API 文档与代码放在一起。
我们是 JS 全栈, JS 有一套 JSDoc 标准,适用于非 API 场景的文档编写,依照这个标准,有一个 APIDoc 工具,可以用类似 JSDoc 的方式在代码中用注释编写 API 文档,但是在实际应用过程中感觉不适合我们的应用场景,所以自己写了一个 URIDoc https://www.npmjs.com/package/uridoc 目前还是 v1 的初级阶段,欢迎 Fork 和 PullRequest |
77
eurry 2017-04-14 08:33:39 +08:00
https://www.showdoc.cc/
showDoc |
78
hareandlion 2017-04-14 08:34:50 +08:00 via iPhone
口口相传 +1
|
79
tangbl93 2017-04-14 08:41:36 +08:00
word + 1
|
81
yellowV2ex 2017-04-14 08:47:46 +08:00
腾讯微信的公众号开发文档就是 word ,最开始的时候,里面引号还是中文的。
|
82
yellowV2ex 2017-04-14 08:48:32 +08:00
|
83
loading 2017-04-14 08:50:36 +08:00
自己看代码
|
84
zongren 2017-04-14 08:54:21 +08:00 1
QQ 聊天记录
|
85
zcwlwen 2017-04-14 09:16:26 +08:00
写 markdown 扔在 gitlab 上
|
86
BearD01001 2017-04-14 09:35:43 +08:00
额,公司的 boss 系统有 API 文档检索功能,虽然界面粗糙,不过挺实用
|
87
HuntBao 2017-04-14 09:39:57 +08:00 1
我司自己开发的接口管理系统: https://nei.netease.com/
|
88
silenceeeee 2017-04-14 09:42:03 +08:00
写 word 扔 svn ,己准备离职!
|
89
stackboom 2017-04-14 09:43:29 +08:00
之前 swagger ,现在 RAP
|
91
Raidal 2017-04-14 09:56:46 +08:00
在用 [aglio]( https://github.com/danielgtaylor/aglio) ,不过数据多了后会有一点点慢。
|
92
roricon 2017-04-14 10:33:37 +08:00
sphinx 为啥没人提起呢.
|
93
chipmuck 2017-04-14 10:39:43 +08:00
https://www.v2ex.com/t/340795 难怪看的眼熟。。。。
|
94
heaunter 2017-04-14 10:43:44 +08:00 via Android
必须小幺鸡啊……团队已从 RAP 切换到小幺鸡了
|
96
magiclobster 2017-04-14 15:49:19 +08:00
为什么不用 oschina 啊..
|
97
changs1986 2017-04-14 18:58:03 +08:00
apidoc
|
98
andychen1 2020-09-04 14:20:56 +08:00
api-mom.com 我司用这个
|