各位公司的 API 接口文档是用的什么方式？

[aschoolboy]

之前公司的 API 接口文档写在 word 里，放在 github 上。
缺点很多，不能同时编辑，一同时编辑就冲突.
我趁一期项目结束，搭了个开源 API 接口网站：eolinker。
给师父看了，说可以，叫我把所有接口都牵进去了。准备让所有同事用了。
结果有的同事一看感觉不方便，说可以用 markdown 来写。
又安排我找个用 markdown 写的 api 文档模板

所以想问问大家的 api 接口文档是采用什么方式的？

[wangcansun]

swagger?=>代码生成文档。
markdown 模式的=>Apiary ？

[cnbattle]

公司用的 apizza

[cnbattle]

可以用 http://www.xiaoyaoji.cn/ 支持 md

[DiverRD]

我推荐 Yapi 楼主可以搜搜看

[billlee]

口述

[aschoolboy]

@billlee #5 哈哈 可以

[mhtt]

我要回农村

[yidinghe]

写了一个框架，要求必须用注解语法来定义接口，然后提供一个 web 页面供查看注解内容。所以文档和代码是同步的。

[PHPJit]

eolinker

[aschoolboy]

@mhtt #7 咋啦兄弟

[RangerWolf]

虽然楼主你搭建的 eolinker 确实强大， 但是我组就用的 markdown

感觉足够了。。。
因为在打开 git 项目的时候， 顺手就能看到 哦， 这个项目的 Readme 有大概介绍。 形成自然反馈了。


可能 API 比较多比较复杂的场景适合 eolinker ？

[dengtongcai]

postman 临时文档……

[oneisall]

graphql = =

[TommyLemon]

自动生成的
apijson.org/

后端接口和文档自动化，前端(客户端) 定制返回 JSON 的数据和结构！
github.com/TommyLemon/APIJSON

[TommyLemon]

@TommyLemon 不需要写任何代码哦

[voidcomma]

@billlee 之前我对接的后端真的是过来跟我口述的，或者在微信发条消息……有一次直接把代码截图给我。我搭了个 swagger 又不想学写文件，只好让建个 md 让他更新在上面。🤣

[TommyLemon]

格式是这样的，发不了图片凑活看吧，右侧往下翻，在自动生成的代码下方。

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 | 不限 | 创建日期

[WEAlex]

没有用 rap2 的么，虽然有一些 bug

[TommyLemon]

@TommyLemon
创作不易，GitHub 右上角点 Star 支持下吧，谢谢^_^
github.com/TommyLemon/APIJSON

[TommyLemon]

@TommyLemon APIJSONAuto 在线工具还有很多其它功能：
自动生成文档，清晰可读永远最新
自动生成请求代码，支持 Android 和 iOS
自动生成 JavaBean 文件，一键下载
自动管理与测试接口用例，一键共享
自动校验与格式化 JSON，支持高亮和收展

创作不易，GitHub 右上角点 Star 支持下吧，谢谢^_^
github.com/TommyLemon/APIJSON

[ioc]

@TommyLemon 我就说一句，你这个除了 mysql，其他数据库都不支持

[opengps]

注释自动生成的 webapi 说明文档

[keenwon]

nei 了解下 https://nei.netease.com/

[chenry]

什麼方式？不存在的。。。
問 Dev 是 Get 還是 POST ？你都試一下
問參數是什麼格式的？你看一下代碼

運維天天和我吐槽~~

[ivanchou]

拿阿里的 Rap 改良的

[loveCoding]

走 rpc ,传输用的 pb 协议 ,感觉还不错

[Ethanp]

showdoc

[xiaqi]

showdoc

[lrh3321]

postman 或者手写 openapi 3.0 格式的文档，然后放到 swagger ui 上看。文档和手动测试一体化，就是后端累死了

[BaiMax]

在用 showdoc,有一键模板

[justfindu]

word 方式可以试试 QQ 的文档共享编辑那个. 真的还挺棒的

[947211232]

搭建内网 github，使用 gitbook 建档

[smilenceX]

听说过德鲁依没？

[CFO]

swagger 改代码时顺手就把文档维护了 本身支持在线文档 也可以用其他工具导出 html pdf

[oppressed6370]

apizza，不过文件夹下不能建立子文件夹

[v2chou]

口口相传 心累 我是前端

[ofooo]

我最近尝试用蚂蚁金服出的语鹊，楼主去看看怎么样吧，不涉及机密的话感觉还不错

[LeungJZ]

口口相传+1.

[Flicker]

就直接用 markdown 写的，文档这个东西只要有一定规范，大家都能看懂就行了。

[cqu1980]

apidoc~~~~~~~~~~~~~~~~

[joeke]

showdoc apizz 都比较好用

[jasonslyvia]

swagger + pont + ts，如丝般顺滑

[jianlu]

showdoc + 1

[adrianXu]

swagger2

[guoyuchuan]

swagger

[TommyLemon]

@adrianXu 你是怎么发出图片的？

[adrianXu]

@TommyLemon #46 截图 command+v

[CabalPHP]

http://demo.cabalphp.com/__docs

[jinhan13789991]

后台口头传述，绝对不会泄露

[specita]

在用 Apiary，不过语法要了解下不怎么方便，学习成本有点高, 正准备换

[IMuMa3]

eoLinker +1

[lydbilibili]

没有文档

[Heanes]

swagger 或者 rap

[tt67wq]

我司一般靠睿智的程序员去源码里面考古

[Smilencer]

之前用 swagger，现在我再推广使用 postman collection, 作为后端必须产出文档之一。前端和测试 MM 都夸我好贴心，后端兄弟对我恨子入骨。。。

[A555]

给个地址 给个例子 自己玩

[TommyLemon]

https://oscimg.oschina.net/oscnet/f123d05a95009216791d54831d266448cac.jpg

自动生成文档，清晰可读永远最新
自动生成请求代码，支持 Android 和 iOS
自动生成 JavaBean 文件，一键下载
自动管理与测试接口用例，一键共享
自动校验与格式化 JSON，支持高亮和收展

有视频教程哦
apijson.org

GitHub 右上角点 Star 支持下吧，谢谢^_^
github.com/TommyLemon/APIJSON

[TommyLemon]

<img src="https://oscimg.oschina.net/oscnet/f123d05a95009216791d54831d266448cac.jpg" />

[TommyLemon]

@Smilencer Swagger,APIDoc 等都要后端写大量注解代码啊，能不恨你么哈哈？
用 APIJSONAuto 好了，全自动生成，一行代码都不用写

[lazypu]

粘贴一段 json, 附上 url, method. 哈哈哈

[matthevv]

Apidoc🤭

[hellopy]

我司：svn+word+excel,wiki

[fuckgfwfuckgfw]

https://github.com/txthinking/frank

[zclHIT]

IDP-Lite..

[yzmm]

swagger+markdown

[shd]

apidoc +1

[skyline45]

word 啊 2333333333

[zavieryip]

showdoc+1

[whypool]

excel

[Lawlieti]

口述

[x537196]

魔改 showdoc

[cai314494687]

自己搭建 eolinker

[Light3]

https://apiview.com/
这个 人少完全 ok

[hasbug]

以前 swagger，现在公司 word···好烦人

[pandaaa]

用的 wiki

[TommyLemon]

https://raw.githubusercontent.com/TommyLemon/StaticResources/master/APIJSON_Auto_doc.jpg

[TommyLemon]

V2EX 评论里发个图片这么麻烦。。。

[Edwards]

@billlee 皮

[NicholasYX]

写个页面，罗列按钮，怎么调用直接写按钮点击事件里面，拿去自己点着玩，右键查看源代码 手动滑稽.

[xrr2016]

之前公司用什么 txt 文件，或者 md，在我的推荐下用了 YApi，很好用的；

[pandasoda]

@billlee 秀

[sakishum]

口传心授

[iFlicker]

@billlee 对的， 反正人家也不看 都是过来问

[Sylphiette]

用过 swagger，showdoc，最终使用 apizza

[jianpanxia]

自己看代码去..

[bufpay]

(bufpay.com 个人收款 API)[https://bufpay.com/page.html] 直接是 html，用 github 的 wiki 也不错呀

[Jameson1559]

。。。我们连口口相传都没有。。全靠慧根自己领悟。。。

[NSAtools]

口口相传，代码连注释也没

[NonClockworkChen]

虽然是老生常谈，但是挺有用的帖子。。。

[fml87]

项目立项的时候有详细的设计文档，项目一期用 swagger，二期、三期、四期接口变动超过 90%，人员也换了一轮，API、消息结构、一些部署配置项就全靠口口相传和猜了

[TingHaiJamiE]

yapi

[randyzhao]

手写 MD。。。

[beny2mor]

rap2

[TommyLemon]

@fml87 Swagger 这种需要后端写大量注解代码的，后期当然维护困难。
用 APIJSONAuto 吧，一行代码都不用写就能自动生成文档
右上角点 Star 支持下吧^_^
github.com/TommyLemon/APIJSON

<img src="https://oscimg.oschina.net/oscnet/f123d05a95009216791d54831d266448cac.jpg" />

[TommyLemon]

@TommyLemon 效果展示(右侧滚动到自动生成的代码的下方)：
apijson。org

[reus]

用函数签名做文档，反正前端看得懂，先写文档，然后把文档复制到代码里，改下一些参数类型，然后加上函数体，就实现了接口

[sutra]

enunciate.

[soulmine]

没有文档

[feiyuanqiu]

@TommyLemon 需要程序员写大量注解，就没有把 swagger 用对

[nwu2Cv8OZ2MZMg39]

rap