这是一个创建于 2643 天前的主题，其中的信息可能已经有所发展或是发生改变。
之前公司的 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 ![](http://www.v2ex.com/static/img/heart_20250818.png?v=c3415183a0b3e9ab1576251be69d7d6d"){kind=small} 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/span> 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 |
Select Language