之前公司的 API 接口文档写在 word 里，放在 github 上。
缺点很多，不能同时编辑，一同时编辑就冲突.
我趁一期项目结束，搭了个开源 API 接口网站：eolinker。
给师父看了，说可以，叫我把所有接口都牵进去了。准备让所有同事用了。
结果有的同事一看感觉不方便，说可以用 markdown 来写。
又安排我找个用 markdown 写的 api 文档模板
所以想问问大家的 api 接口文档是采用什么方式的？
• 请不要在回答技术问题时复制粘贴 AI 生成的内容
This topic created in 3031 days ago, the information mentioned may be changed or developed.
 |
1
swagger?=>代码生成文档。
markdown 模式的=>Apiary ？ |
1 |
cnbattleJul 18, 2018
2
公司用的 apizza
|
|
cnbattleJul 18, 2018
3
可以用 http://www.xiaoyaoji.cn/ 支持 md
|
 |
4
我推荐 Yapi 楼主可以搜搜看
|
 |
5
口述
|
 |
6
@billlee #5 哈哈 可以
|
 |
mhttJul 18, 2018
7
我要回农村
|
 |
8
写了一个框架，要求必须用注解语法来定义接口，然后提供一个 web 页面供查看注解内容。所以文档和代码是同步的。
|
 |
PHPJitJul 18, 2018 via Android
9
eolinker
|
|
10
@mhtt #7 咋啦兄弟
|
 |
RangerWolfJul 18, 2018
11
虽然楼主你搭建的 eolinker 确实强大， 但是我组就用的 markdown
感觉足够了。。。 因为在打开 git 项目的时候， 顺手就能看到 哦， 这个项目的 Readme 有大概介绍。 形成自然反馈了。 可能 API 比较多比较复杂的场景适合 eolinker ？ |
 |
dengtongcaiJul 18, 2018 via Android
12
postman 临时文档……
|
 |
oneisallJul 18, 2018
13
graphql = =
|
 |
TommyLemonJul 18, 2018
14
|
|
TommyLemonJul 18, 2018
15
@TommyLemon 不需要写任何代码哦
|
 |
voidcommaJul 18, 2018 via iPhone
16
@billlee 之前我对接的后端真的是过来跟我口述的，或者在微信发条消息……有一次直接把代码截图给我。我搭了个 swagger 又不想学写文件，只好让建个 md 让他更新在上面。🤣
|
|
TommyLemonJul 18, 2018
17
格式是这样的，发不了图片凑活看吧，右侧往下翻，在自动生成的代码下方。
2. User 说明: 用户公开信息表。 对安全要求高，不想泄漏真实名称。对外名称为 User 字段: 名称 | 类型 | 最大长度| 详细说明 id | Long | 15 | 唯一标识 sex | Integer | 2 | 性别：0-男 1-女 name | String | 20 | 名称 tag | String | 45 | 标签 head | String | 300 | 头像 url contactIdList | List | 不限 | 联系人 id 列表 pictureList | List | 不限 | 照片列表 date | Timestamp | 不限 | 创建日期 |
 |
WEAlexJul 18, 2018 via Android
18
没有用 rap2 的么，虽然有一些 bug
|
|
TommyLemonJul 18, 2018
19
|
|
TommyLemonJul 18, 2018
20
@TommyLemon APIJSONAuto 在线工具还有很多其它功能：
自动生成文档，清晰可读永远最新 自动生成请求代码，支持 Android 和 iOS 自动生成 JavaBean 文件，一键下载 自动管理与测试接口用例，一键共享 自动校验与格式化 JSON，支持高亮和收展 创作不易，GitHub 右上角点 Star 支持下吧，谢谢^_^ github.com/TommyLemon/APIJSON |
 |
iocJul 18, 2018 via Android
21
@TommyLemon 我就说一句，你这个除了 mysql，其他数据库都不支持
|
 |
opengpsJul 18, 2018 via Android
22
注释自动生成的 webapi 说明文档
|
 |
keenwonJul 19, 2018
23
nei 了解下 https://nei.netease.com/
|
 |
chenryJul 19, 2018
24
什麼方式？不存在的。。。
問 Dev 是 Get 還是 POST ？你都試一下 問參數是什麼格式的？你看一下代碼 運維天天和我吐槽~~ |
 |
ivanchouJul 19, 2018 via Android
25
拿阿里的 Rap 改良的
|
 |
loveCodingJul 19, 2018
26
走 rpc ,传输用的 pb 协议 ,感觉还不错
|
 |
EthanpJul 19, 2018 via Android
27
showdoc
|
 |
xiaqiJul 19, 2018 via Android
28
showdoc
|
 |
lrh3321Jul 19, 2018 via Android
29
postman 或者手写 openapi 3.0 格式的文档，然后放到 swagger ui 上看。文档和手动测试一体化，就是后端累死了
|
 |
30
在用 showdoc,有一键模板
|
 |
justfinduJul 19, 2018
31
word 方式可以试试 QQ 的文档共享编辑那个. 真的还挺棒的
|
 |
947211232Jul 19, 2018
32
搭建内网 github，使用 gitbook 建档
|
 |
smilenceXJul 19, 2018
33
听说过德鲁依没？
|
 |
34
swagger 改代码时顺手就把文档维护了 本身支持在线文档 也可以用其他工具导出 html pdf
|
 |
oppressed6370Jul 19, 2018
35
apizza，不过文件夹下不能建立子文件夹
|
 |
v2chouJul 19, 2018
36
口口相传 心累 我是前端
|
 |
ofoooJul 19, 2018 via iPhone
37
我最近尝试用蚂蚁金服出的语鹊，楼主去看看怎么样吧，不涉及机密的话感觉还不错
|
 |
LeungJZJul 19, 2018
38
口口相传+1.
|
 |
FlickerJul 19, 2018 via Android
39
就直接用 markdown 写的，文档这个东西只要有一定规范，大家都能看懂就行了。
|
 |
cqu1980Jul 19, 2018
40
apidoc~~~~~~~~~~~~~~~~
|
 |
joekeJul 19, 2018
41
showdoc apizz 都比较好用
|
 |
42
swagger + pont + ts，如丝般顺滑
|
 |
jianluJul 19, 2018
43
showdoc + 1
|
 |
adrianXuJul 19, 2018
44
swagger2
 |
 |
guoyuchuanJul 19, 2018
45
swagger
|
|
TommyLemonJul 19, 2018
46
@adrianXu 你是怎么发出图片的？
|
|
adrianXuJul 19, 2018
47
@TommyLemon #46 截图 command+v
|
 |
CabalPHPJul 19, 2018
48
|
 |
jinhan13789991Jul 19, 2018
49
后台口头传述，绝对不会泄露
|
 |
specitaJul 19, 2018
50
在用 Apiary，不过语法要了解下不怎么方便，学习成本有点高, 正准备换
|
 |
IMuMa3Jul 19, 2018
51
eoLinker +1
|
 |
lydbilibiliJul 19, 2018
52
没有文档
|
 |
HeanesJul 19, 2018
53
swagger 或者 rap
|
 |
tt67wqJul 19, 2018
54
我司一般靠睿智的程序员去源码里面考古
|
 |
SmilencerJul 19, 2018
55
之前用 swagger，现在我再推广使用 postman collection, 作为后端必须产出文档之一。前端和测试 MM 都夸我好贴心，后端兄弟对我恨子入骨。。。
|
 |
A555Jul 19, 2018
56
给个地址 给个例子 自己玩
|
|
TommyLemonJul 19, 2018
57
https://oscimg.oschina.net/oscnet/f123d05a95009216791d54831d266448cac.jpg
自动生成文档，清晰可读永远最新 自动生成请求代码，支持 Android 和 iOS 自动生成 JavaBean 文件，一键下载 自动管理与测试接口用例，一键共享 自动校验与格式化 JSON，支持高亮和收展 有视频教程哦 apijson.org GitHub 右上角点 Star 支持下吧，谢谢^_^ github.com/TommyLemon/APIJSON |
|
TommyLemonJul 19, 2018
58
|
|
TommyLemonJul 19, 2018
59
@Smilencer Swagger,APIDoc 等都要后端写大量注解代码啊，能不恨你么哈哈？
用 APIJSONAuto 好了，全自动生成，一行代码都不用写 |
 |
lazypuJul 19, 2018
60
粘贴一段 json, 附上 url, method. 哈哈哈
|
 |
matthevvJul 19, 2018 via iPhone
61
Apidoc🤭
|
 |
hellopyJul 19, 2018
62
我司：svn+word+excel,wiki
|
 |
fuckgfwfuckgfwJul 19, 2018 via Android
63
|
 |
zclHITJul 19, 2018 via iPhone
64
IDP-Lite..
|
 |
yzmmJul 19, 2018
65
swagger+markdown
|
 |
shdJul 19, 2018
66
apidoc +1
|
 |
skyline45Jul 19, 2018
67
word 啊 2333333333
|
 |
zavieryipJul 19, 2018
68
showdoc+1
|
 |
whypoolJul 19, 2018
69
excel
|
 |
LawlietiJul 19, 2018
70
口述
|
 |
nimonewJul 19, 2018
71
魔改 showdoc
|
 |
cai314494687Jul 19, 2018
72
自己搭建 eolinker
|
 |
Light3Jul 19, 2018
73
https://apiview.com/
这个 人少完全 ok |
 |
hasbugJul 19, 2018
74
以前 swagger，现在公司 word···好烦人
|
 |
pandaaaJul 19, 2018 via Android
75
用的 wiki
|
|
TommyLemonJul 19, 2018
76
|
|
TommyLemonJul 19, 2018
77
V2EX 评论里发个图片这么麻烦。。。
|
 |
NicholasYXJul 19, 2018
79
写个页面，罗列按钮，怎么调用直接写按钮点击事件里面，拿去自己点着玩，右键查看源代码 手动滑稽.
|
 |
xrr2016Jul 19, 2018
80
之前公司用什么 txt 文件，或者 md，在我的推荐下用了 YApi，很好用的；
|
 |
sakishumJul 19, 2018
82
口传心授
|
 |
SylphietteJul 19, 2018
84
用过 swagger，showdoc，最终使用 apizza
|
 |
jianpanxiaJul 19, 2018
85
自己看代码去..
 |
 |
bufpayJul 19, 2018
86
(bufpay.com 个人收款 API)[https://bufpay.com/page.html] 直接是 html，用 github 的 wiki 也不错呀
|
 |
Jameson1559Jul 19, 2018
87
。。。我们连口口相传都没有。。全靠慧根自己领悟。。。
|
 |
NSAtoolsJul 19, 2018
88
口口相传，代码连注释也没
|
 |
NonClockworkChenJul 19, 2018
89
虽然是老生常谈，但是挺有用的帖子。。。
|
 |
fml87Jul 19, 2018
90
项目立项的时候有详细的设计文档，项目一期用 swagger，二期、三期、四期接口变动超过 90%，人员也换了一轮，API、消息结构、一些部署配置项就全靠口口相传和猜了
|
 |
TingHaiJamiEJul 19, 2018
91
yapi
|
 |
randyzhaoJul 19, 2018
92
手写 MD。。。
|
 |
beny2morJul 19, 2018
93
rap2
|
|
TommyLemonJul 19, 2018
94
@fml87 Swagger 这种需要后端写大量注解代码的，后期当然维护困难。
用 APIJSONAuto 吧，一行代码都不用写就能自动生成文档 右上角点 Star 支持下吧^_^ github.com/TommyLemon/APIJSON <img src="https://oscimg.oschina.net/oscnet/f123d05a95009216791d54831d266448cac.jpg" /> |
|
TommyLemonJul 19, 2018
95
@TommyLemon 效果展示(右侧滚动到自动生成的代码的下方)：
apijson。org |
 |
reusJul 19, 2018
96
用函数签名做文档，反正前端看得懂，先写文档，然后把文档复制到代码里，改下一些参数类型，然后加上函数体，就实现了接口
|
 |
sutraJul 19, 2018
97
enunciate.
|
 |
soulmineJul 19, 2018
98
没有文档
|
 |
feiyuanqiuJul 19, 2018
99
|
 |
nwu2Cv8OZ2MZMg39Jul 19, 2018 via Android
100
rap
|
Select Language