之前公司的 API 接口文档写在 word 里,放在 github 上。
缺点很多,不能同时编辑,一同时编辑就冲突.
我趁一期项目结束,搭了个开源 API 接口网站:eolinker。
给师父看了,说可以,叫我把所有接口都牵进去了。准备让所有同事用了。
结果有的同事一看感觉不方便,说可以用 markdown 来写。
又安排我找个用 markdown 写的 api 文档模板
所以想问问大家的 api 接口文档是采用什么方式的?
1
wangcansun 2018-07-18 20:15:21 +08:00 1
swagger?=>代码生成文档。
markdown 模式的=>Apiary ? |
2
cnbattle 2018-07-18 20:24:01 +08:00
公司用的 apizza
|
3
cnbattle 2018-07-18 20:25:16 +08:00
可以用 http://www.xiaoyaoji.cn/ 支持 md
|
4
DiverRD 2018-07-18 20:48:49 +08:00 via iPhone 1
我推荐 Yapi 楼主可以搜搜看
|
5
billlee 2018-07-18 21:24:12 +08:00 4
口述
|
6
aschoolboy OP @billlee #5 哈哈 可以
|
7
mhtt 2018-07-18 21:35:51 +08:00
我要回农村
|
8
yidinghe 2018-07-18 22:01:38 +08:00 via Android 1
写了一个框架,要求必须用注解语法来定义接口,然后提供一个 web 页面供查看注解内容。所以文档和代码是同步的。
|
9
PHPJit 2018-07-18 22:02:36 +08:00 via Android
eolinker
|
10
aschoolboy OP @mhtt #7 咋啦兄弟
|
11
RangerWolf 2018-07-18 22:45:48 +08:00
虽然楼主你搭建的 eolinker 确实强大, 但是我组就用的 markdown
感觉足够了。。。 因为在打开 git 项目的时候, 顺手就能看到 哦, 这个项目的 Readme 有大概介绍。 形成自然反馈了。 可能 API 比较多比较复杂的场景适合 eolinker ? |
12
dengtongcai 2018-07-18 22:58:50 +08:00 via Android
postman 临时文档……
|
13
oneisall 2018-07-18 23:00:52 +08:00
graphql = =
|
14
TommyLemon 2018-07-18 23:05:07 +08:00
|
15
TommyLemon 2018-07-18 23:05:32 +08:00
@TommyLemon 不需要写任何代码哦
|
16
xiaojie668329 2018-07-18 23:09:34 +08:00 via iPhone
@billlee 之前我对接的后端真的是过来跟我口述的,或者在微信发条消息……有一次直接把代码截图给我。我搭了个 swagger 又不想学写文件,只好让建个 md 让他更新在上面。🤣
|
17
TommyLemon 2018-07-18 23:09:39 +08:00
格式是这样的,发不了图片凑活看吧,右侧往下翻,在自动生成的代码下方。
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 | 不限 | 创建日期 |
18
WEAlex 2018-07-18 23:09:47 +08:00 via Android
没有用 rap2 的么,虽然有一些 bug
|
19
TommyLemon 2018-07-18 23:10:26 +08:00
|
20
TommyLemon 2018-07-18 23:14:37 +08:00
@TommyLemon APIJSONAuto 在线工具还有很多其它功能:
自动生成文档,清晰可读永远最新 自动生成请求代码,支持 Android 和 iOS 自动生成 JavaBean 文件,一键下载 自动管理与测试接口用例,一键共享 自动校验与格式化 JSON,支持高亮和收展 创作不易,GitHub 右上角点 Star 支持下吧,谢谢^_^ github.com/TommyLemon/APIJSON |
21
ioc 2018-07-18 23:16:31 +08:00 via Android
@TommyLemon 我就说一句,你这个除了 mysql,其他数据库都不支持
|
22
opengps 2018-07-18 23:28:23 +08:00 via Android
注释自动生成的 webapi 说明文档
|
23
keenwon 2018-07-19 00:01:45 +08:00
nei 了解下 https://nei.netease.com/
|
24
chenry 2018-07-19 00:52:59 +08:00
什麼方式?不存在的。。。
問 Dev 是 Get 還是 POST ?你都試一下 問參數是什麼格式的?你看一下代碼 運維天天和我吐槽~~ |
25
ivanchou 2018-07-19 02:27:18 +08:00 via Android
拿阿里的 Rap 改良的
|
26
loveCoding 2018-07-19 06:20:57 +08:00
走 rpc ,传输用的 pb 协议 ,感觉还不错
|
27
Ethanp 2018-07-19 06:23:46 +08:00 via Android
showdoc
|
28
xiaqi 2018-07-19 06:34:55 +08:00 via Android
showdoc
|
29
lrh3321 2018-07-19 07:23:48 +08:00 via Android
postman 或者手写 openapi 3.0 格式的文档,然后放到 swagger ui 上看。文档和手动测试一体化,就是后端累死了
|
30
BaiMax 2018-07-19 08:23:28 +08:00 via Android 1
在用 showdoc,有一键模板
|
31
justfindu 2018-07-19 08:27:26 +08:00
word 方式可以试试 QQ 的文档共享编辑那个. 真的还挺棒的
|
32
947211232 2018-07-19 08:54:03 +08:00
搭建内网 github,使用 gitbook 建档
|
33
smilenceX 2018-07-19 08:55:02 +08:00
听说过德鲁依没?
|
34
CFO 2018-07-19 08:57:53 +08:00 via Android 2
swagger 改代码时顺手就把文档维护了 本身支持在线文档 也可以用其他工具导出 html pdf
|
35
cyokvip 2018-07-19 08:58:06 +08:00
apizza,不过文件夹下不能建立子文件夹
|
36
v2chou 2018-07-19 09:02:35 +08:00
口口相传 心累 我是前端
|
37
ofooo 2018-07-19 09:04:52 +08:00 via iPhone
我最近尝试用蚂蚁金服出的语鹊,楼主去看看怎么样吧,不涉及机密的话感觉还不错
|
38
LeungJZ 2018-07-19 09:06:01 +08:00
口口相传+1.
|
39
Flicker 2018-07-19 09:11:42 +08:00 via Android
就直接用 markdown 写的,文档这个东西只要有一定规范,大家都能看懂就行了。
|
40
cqu1980 2018-07-19 09:12:48 +08:00
apidoc~~~~~~~~~~~~~~~~
|
41
joeke 2018-07-19 09:14:03 +08:00
showdoc apizz 都比较好用
|
42
jasonslyvia 2018-07-19 09:18:40 +08:00 1
swagger + pont + ts,如丝般顺滑
|
43
jianlu 2018-07-19 09:22:38 +08:00
showdoc + 1
|
44
adrianXu 2018-07-19 09:35:32 +08:00
swagger2
|
45
guoyuchuan 2018-07-19 09:38:45 +08:00
swagger
|
46
TommyLemon 2018-07-19 09:53:03 +08:00
@adrianXu 你是怎么发出图片的?
|
47
adrianXu 2018-07-19 09:55:10 +08:00
@TommyLemon #46 截图 command+v
|
48
CabalPHP 2018-07-19 09:56:12 +08:00
|
49
jinhan13789991 2018-07-19 09:57:14 +08:00
后台口头传述,绝对不会泄露
|
50
specita 2018-07-19 10:02:01 +08:00
在用 Apiary,不过语法要了解下不怎么方便,学习成本有点高, 正准备换
|
51
IMuMa3 2018-07-19 10:03:17 +08:00
eoLinker +1
|
52
lydbilibili 2018-07-19 10:06:18 +08:00
没有文档
|
53
Heanes 2018-07-19 10:09:06 +08:00
swagger 或者 rap
|
54
tt67wq 2018-07-19 10:40:59 +08:00
我司一般靠睿智的程序员去源码里面考古
|
55
Smilencer 2018-07-19 10:43:43 +08:00
之前用 swagger,现在我再推广使用 postman collection, 作为后端必须产出文档之一。前端和测试 MM 都夸我好贴心,后端兄弟对我恨子入骨。。。
|
56
A555 2018-07-19 10:47:24 +08:00
给个地址 给个例子 自己玩
|
57
TommyLemon 2018-07-19 10:55:55 +08:00
https://oscimg.oschina.net/oscnet/f123d05a95009216791d54831d266448cac.jpg
自动生成文档,清晰可读永远最新 自动生成请求代码,支持 Android 和 iOS 自动生成 JavaBean 文件,一键下载 自动管理与测试接口用例,一键共享 自动校验与格式化 JSON,支持高亮和收展 有视频教程哦 apijson.org GitHub 右上角点 Star 支持下吧,谢谢^_^ github.com/TommyLemon/APIJSON |
58
TommyLemon 2018-07-19 10:56:44 +08:00
|
59
TommyLemon 2018-07-19 10:58:27 +08:00
@Smilencer Swagger,APIDoc 等都要后端写大量注解代码啊,能不恨你么哈哈?
用 APIJSONAuto 好了,全自动生成,一行代码都不用写 |
60
linxl 2018-07-19 11:00:21 +08:00
粘贴一段 json, 附上 url, method. 哈哈哈
|
61
matthevv 2018-07-19 11:00:45 +08:00 via iPhone
Apidoc🤭
|
62
hellopy 2018-07-19 11:01:40 +08:00
我司:svn+word+excel,wiki
|
63
fuckgfwfuckgfw 2018-07-19 11:03:30 +08:00 via Android
|
64
zclHIT 2018-07-19 11:06:31 +08:00 via iPhone
IDP-Lite..
|
65
yzmm 2018-07-19 11:09:02 +08:00
swagger+markdown
|
66
shd 2018-07-19 11:13:32 +08:00
apidoc +1
|
67
skyline45 2018-07-19 11:19:09 +08:00
word 啊 2333333333
|
68
zavieryip 2018-07-19 11:23:37 +08:00
showdoc+1
|
69
whypool 2018-07-19 11:28:03 +08:00
excel
|
70
Lawlieti 2018-07-19 11:30:12 +08:00
口述
|
71
x537196 2018-07-19 11:33:16 +08:00
魔改 showdoc
|
72
cai314494687 2018-07-19 11:38:47 +08:00
自己搭建 eolinker
|
73
Light3 2018-07-19 11:43:41 +08:00
https://apiview.com/
这个 人少完全 ok |
74
hasbug 2018-07-19 11:50:34 +08:00
以前 swagger,现在公司 word···好烦人
|
75
pandaaa 2018-07-19 11:53:00 +08:00 via Android
用的 wiki
|
76
TommyLemon 2018-07-19 12:17:58 +08:00
|
77
TommyLemon 2018-07-19 12:19:04 +08:00
V2EX 评论里发个图片这么麻烦。。。
|
79
NicholasYX 2018-07-19 12:52:44 +08:00
写个页面,罗列按钮,怎么调用直接写按钮点击事件里面,拿去自己点着玩,右键查看源代码 手动滑稽.
|
80
xrr2016 2018-07-19 13:01:57 +08:00
之前公司用什么 txt 文件,或者 md,在我的推荐下用了 YApi,很好用的;
|
82
sakishum 2018-07-19 13:11:36 +08:00
口传心授
|
84
Heimo 2018-07-19 13:45:14 +08:00
用过 swagger,showdoc,最终使用 apizza
|
85
jianpanxia 2018-07-19 13:47:08 +08:00
自己看代码去..
|
86
bufpay 2018-07-19 13:48:07 +08:00
(bufpay.com 个人收款 API)[https://bufpay.com/page.html] 直接是 html,用 github 的 wiki 也不错呀
|
87
Jameson1559 2018-07-19 14:08:32 +08:00
。。。我们连口口相传都没有。。全靠慧根自己领悟。。。
|
88
NSAtools 2018-07-19 14:09:45 +08:00
口口相传,代码连注释也没
|
89
NonClockworkChen 2018-07-19 15:28:14 +08:00
虽然是老生常谈,但是挺有用的帖子。。。
|
90
fml87 2018-07-19 15:35:15 +08:00
项目立项的时候有详细的设计文档,项目一期用 swagger,二期、三期、四期接口变动超过 90%,人员也换了一轮,API、消息结构、一些部署配置项就全靠口口相传和猜了
|
91
TingHaiJamiE 2018-07-19 15:36:00 +08:00
yapi
|
92
randyzhao 2018-07-19 15:39:19 +08:00
手写 MD。。。
|
93
beny2mor 2018-07-19 15:42:12 +08:00
rap2
|
94
TommyLemon 2018-07-19 15:43:07 +08:00
@fml87 Swagger 这种需要后端写大量注解代码的,后期当然维护困难。
用 APIJSONAuto 吧,一行代码都不用写就能自动生成文档 右上角点 Star 支持下吧^_^ github.com/TommyLemon/APIJSON <img src="https://oscimg.oschina.net/oscnet/f123d05a95009216791d54831d266448cac.jpg" /> |
95
TommyLemon 2018-07-19 15:47:06 +08:00
@TommyLemon 效果展示(右侧滚动到自动生成的代码的下方):
apijson。org |
96
reus 2018-07-19 15:52:46 +08:00
用函数签名做文档,反正前端看得懂,先写文档,然后把文档复制到代码里,改下一些参数类型,然后加上函数体,就实现了接口
|
97
sutra 2018-07-19 15:55:24 +08:00
enunciate.
|
98
soulmine 2018-07-19 16:00:24 +08:00
没有文档
|
99
feiyuanqiu 2018-07-19 16:28:22 +08:00
|
100
nwu2Cv8OZ2MZMg39 2018-07-19 16:29:43 +08:00 via Android
rap
|