这是一个创建于 2321 天前的主题，其中的信息可能已经有所发展或是发生改变。
我是公司后端开发，目前公司接口使用的是 word 记录，在 svn 上 管理的。 现在一个工程的接口文档到了快 200 页，电脑编辑保存下文档真是卡的不行。
想问下大家都是管理接口文档的，最好是离线的，公司不允许接口文档上外网。  | 1 zsdroid 2019-06-05 11:28:29 +08:00  1 yapi |
 | 2 acumen 2019-06-05 11:30:21 +08:00 via iPhone 67 口口相传，分布式存储在脑海 |
 | 3 lihongjie0209 2019-06-05 11:31:07 +08:00 既然是后端, 直接看代码. |
 | 4 Vegetable 2019-06-05 11:32:30 +08:00 现在是 yapi,以前也尝试过 gitbook 来做,怪不方便的. |
 | 5 SirLostWhite 2019-06-05 11:34:49 +08:00 一开始用的 apizza 后来转用 eolinker 还挺好用的 |
 | 6 skiy 2019-06-05 11:36:35 +08:00 API 文档？管理平台好多。我在用的是 mindoc。 |
 | 7 a330202207 2019-06-05 11:37:54 +08:00 showdoc |
 | 8 doco 2019-06-05 11:38:21 +08:00 之前是 showDoc, 现在是 YAPI, 然而后台都不喜欢写接口文档 |
 | 9 rexyan 2019-06-05 11:39:29 +08:00 跟着项目走，传 git |
 | 10 chinvo 2019-06-05 11:40:37 +08:00 via iPhone 1 openapi + web ui |
 | 11 rexqian 2019-06-05 11:42:37 +08:00 yapi , 同时后端集成了 springfox 生成 swagger 文档, 然后 swagger 的文档可以直接导入到 yapi |
 | 12 kevinlm 2019-06-05 11:46:16 +08:00 via iPhone 9 一杯茶，一盒烟，一个参数传一天 |
 | 13 razaura 2019-06-05 11:50:15 +08:00 1 swagger |
 | 14 introle 2019-06-05 11:51:02 +08:00 via iPhone 1 swagger +1 |
 | 15 Caballarii 2019-06-05 11:53:21 +08:00 肯定 swagger 啊，能直接试比看文档强多了好吧 |
 | 16 pengjl 2019-06-05 12:00:38 +08:00 swagger+1 |
 | 17 zhuwd 2019-06-05 12:13:07 +08:00 via iPhone yapi |
 | 18 cccy0 2019-06-05 12:25:15 +08:00 postman |
 | 19 fengxianqi 2019-06-05 12:28:44 +08:00 内网部署 yapi 应该是最合适的了 |
 | 20 EastLord 2019-06-05 12:29:44 +08:00 swagger |
 | 21 mylxsw 2019-06-05 12:31:13 +08:00 via Android 推荐用 wizard，内网部署 https://github.com/mylxsw/wizard |
 | 22 anankun OP 1 用 swagger 写，代码侵入感觉太多了。单后端看还行，前端看有些实体的参数确定不了 |
 | 23 brust 2019-06-05 12:31:48 +08:00 swagger jsonapi |
 | 24 TommyLemon 2019-06-05 12:31:57 +08:00 1  比 Postman，Swagger，EOLinker，Rap，apidoc 等一堆工具在基础的文档、测试方面要强大易用很多。 自动化接口管理工具，自动生成代码、自动静态检查、自动化回归测试、自动生成文档与注释等。 * 自动生成接口文档，清晰可读永远最新 * 自动校验与格式化，支持高亮和收展 * 自动生成各种语言代码，一键下载 * 自动管理与测试接口用例，一键共享 * 自动给请求 JSON 加注释，一键切换 * 自动保存历史请求记录，一键恢复 代码已开源，可以点 Star 支持下哦 ^_^ github.com/TommyLemon/APIJSONAuto |
| 25 TommyLemon 2019-06-05 12:32:55 +08:00 @TommyLemon 可以拿源码部署到公司内部，自带测试用例 Demo，有部署文档教程、使用视频教程 等 |
| 26 TommyLemon 2019-06-05 12:33:28 +08:00  |
 | 27 Macolor21 2019-06-05 12:46:54 +08:00 6 ....*** 楼上这个又来了。。真的是 |
 | 28 chendy 2019-06-05 12:57:00 +08:00 我猜会有人来推他的 apijson （虽然 block 了… |
 | 29 liuxey 2019-06-05 12:59:38 +08:00 现在看到 APIJSON 就烦，不管是作品还是作者！ |
 | 30 salamanderMH 2019-06-05 13:01:32 +08:00 yapi |
 | 32 coosir 2019-06-05 13:04:40 +08:00 eolinker |
 | 33 jorneyr 2019-06-05 13:06:49 +08:00 我们使用 yApi |
 | 34 littlewing 2019-06-05 13:08:38 +08:00 不让上外网为什么就得是离线的？难道你们公司没内网吗 |
 | 35 via 2019-06-05 13:13:05 +08:00 哈哈哈哈，我也觉得那个人会来。 ---- 我目前用的是 gitbook cli，但是当 md 文件数量上到 100 多以后，build 一次很慢，大概需要 20 秒。gitbook 还有个好处是可以生成一本 PDF，带封面和目录，可以说很好看了。但是 gitbook cli 目前似乎不维护了，他们家现在主推他们的在线托管服务。 然后用 vscode 来编辑。 |
| 36 anankun OP @littlewing 有道理，看了回复发现部署个内网 yapi 也是很好。 |
 | 37 xuanbg 2019-06-05 13:38:54 +08:00 直接写 readme.md 里面，gitlab 里面和后端项目在一起。格式是有模板的，http://api.yitu8.cn 可以参考下，顺便提点意见。 |
 | 39 ooee2016 2019-06-05 13:46:33 +08:00 eolinker |
| 40 ooee2016 2019-06-05 13:46:52 +08:00 @SirLostWhite 一样 |
 | 42 Takamine 2019-06-05 13:52:58 +08:00 via Android conference。 |
 | 44 hnbcinfo 2019-06-05 13:58:29 +08:00 项目开发中，做好接口规范，接口名称和请求响应参数描述，利用 Attribute 及注释标注。每次项目编译，利用 Yapi 的开放接口，自动同步已经开发好的接口，包含接口分组、字段注释，接口描述等完整信息。 |
 | 45 ggicci 2019-06-05 13:58:59 +08:00 我喜欢用 apiary。 1. 我把接口文档和源码一起维护； 2. 每次更新文档都提交到 apiary 服务（支持自建，docker 拉一个就好），它会帮你渲染，方便浏览和调试，这个就有点类似 postman 了。 |
| 46 ggicci 2019-06-05 14:01:00 +08:00 加一句，apiary 是 api-blueprint 的 api 文档编写规范，学习曲线稍会偏高。所以用的人可能不是很多。 |
 | 48 axbx 2019-06-05 14:09:36 +08:00 一个 excel,上传到项目的 SVN。 |
| 49 TommyLemon 2019-06-05 14:16:08 +08:00 @Macolor21 @liuxey @via 看清楚 APIJSONAuto 和 APIJSON 是两个项目 自动化接口管理工具 （ 300 + Star ） github.com/TommyLemon/APIJSONAuto/ 自动化接口与文档 ORM 库（ 6100 + Star ） github.com/APIJSON/APIJSON/ 再说人家提问，回答问题有啥不对？对某些需要的人也是有帮助的。 你们这种宣泄情绪的评论才是违反 V2EX 规则的。 “请尽量让自己的回复能够对别人有帮助” |
 | 50 zaul 2019-06-05 14:16:39 +08:00 小幺鸡 |
| 51 TommyLemon 2019-06-05 14:17:38 +08:00 @TommyLemon APIJSONAuto-自动化接口管理工具 类似 postman，对代码无任何入侵，也不需要写任何代码哦 |
 | 52 Kenyore 2019-06-05 14:29:57 +08:00 swagger 大法好 |
 | 53 Edsie 2019-06-05 14:58:27 +08:00 能把他屏蔽了吗？ |
 | 54 zgcwkj 2019-06-05 15:04:32 +08:00 口口相传（就是嘴对嘴，一张对一张，传递下去） |
 | 56 robinlovemaggie 2019-06-05 15:12:48 +08:00 离线版的我觉得不如搞个小本本记下了得了 |
 | 57 ibugeek 2019-06-05 15:19:36 +08:00 现在用 eolinker，感觉比 yapi 好一些 |
 | 58 ifane 2019-06-05 15:22:16 +08:00 apidoc 的没有么 |
 | 59 cctv1005s927 2019-06-05 15:26:48 +08:00 看到 apijson 就烦.. |
 | 60 leafre 2019-06-05 15:29:34 +08:00 swagger |
 | 61 wocanmei 2019-06-05 15:34:57 +08:00 apijson 木哈哈，eolinker 不错，没人用吗，免费版够用了，界面也挺好看 |
 | 62 jingyulong 2019-06-05 15:39:20 +08:00 via iPhone 说有预感 API JSON 的会来推广的，是想笑死我继承我的花呗吗？ |
 | 64 EmotionV 2019-06-05 16:04:44 +08:00 yapi+swagger |
 | 66 jaryur 2019-06-05 16:14:24 +08:00 via Android 如果是 HTTP 文档，swagger，eolinker 开源版基本都可以满足，我们现在是基于 dubbo 微服务化，虽然有 dubbo-swagger 但是个人觉得需要开发人员在代码里面编写太多的 api 注释，相当于 api 文档入侵了代码，最近在实现一个基于 javadoc 插件生成 api 文档，然后用静态页面服务器统计集中管理和展示，目的为了解决微服务场景下的 rpc api 文档治理，有过类似实践的可以一起交流下 |
 | 67 feihuxiongdi 2019-06-05 16:17:22 +08:00 @acumen 真!分布式 |
 | 68 karllynn 2019-06-05 16:20:00 +08:00 我们都是直接手写的。。其实也不费事 |
 | 69 mapper 2019-06-05 16:22:51 +08:00 用的 ooi 系统，感觉一般。还是需要人工去配置 |
 | 70 wawehi 2019-06-05 16:30:26 +08:00 后端生成或手写编辑 Markdown 格式，放入内网 GIT 库就完事了？ 需要其它格式的都由 md 文件去生成 |
| 71 chendy 2019-06-05 16:35:37 +08:00 @jaryur 终于看到一个用 javadoc 的了…我们是做了个 annotation-processor，扫 spring-mvc 的注解，读参数返回值生成 adoc |
 | 72 rockyou12 2019-06-05 16:35:42 +08:00 spring-fox + swagger，很多人觉得注解入侵代码很难看，但本来也只在 controller 层写，而且 controller 的方法基本就一两行，注解多点也不是很碍事啊 |
 | 73 gabon 2019-06-05 16:48:55 +08:00 via Android SOA 治理工具 |
 | 74 NoKey 2019-06-05 17:00:01 +08:00 请教一下，使用 swagger 的，对于复杂逻辑，或者返回结果需要比较复杂的方式才可以还原的，怎么写的？ 我一直用 markdown 写了放 git 里，最近有人说不用 swagger 就落后了，我想，光文档里写一个返回数据如何使用都要写大半也，写到代码注释里，那还不半屏幕的注释啊。。。 |
| 75 rockyou12 2019-06-05 17:11:03 +08:00 @NoKey 如果只是字段多，嵌套复杂，像 spring-fox 这种是自动扫描类信息的，不需要手写。其它语言基本也有这种 swagger 的自动生成工具 |
| 76 NoKey 2019-06-05 17:15:29 +08:00 @rockyou12 不是嵌套复杂，是业务复杂，服务器发出去的数据，需要指定的方式才能解析出来，这个指定的方式，需要写半夜文档的样子。。。还有，返回去的字段也是嵌套的，比如 json 里面嵌了一个 String，但是这个 String 实际是个 json，swagger 能解析道这个 String 的结构么？ |
| 78 rockyou12 2019-06-05 17:27:26 +08:00 @NoKey swagger 其实现在不只是一个文档工具，也是 open api 这个规范的实现，open api 基本只支持 rest api。你接口不符合 rest 那就没办法了ㄟ( , )ㄏ |
 | 79 BlBana 2019-06-05 17:30:00 +08:00 话说楼主得是渣康的 ... |
 | 80 cwx391497 2019-06-05 17:35:26 +08:00 我也是,我这文档都 400 多页了,大范围编辑真的想死 我的想法是用 html 重写,或者把文档做成 chm 格式的,会比较好维护(积重难返.....) |
 | 81 poisedflw 2019-06-05 17:37:33 +08:00 自己部署一套 eolinker |
 | 82 dif 2019-06-05 17:38:30 +08:00 yapi |
 | 84 thfurior 2019-06-05 17:55:03 +08:00 别问，问就 doc |
| 85 jaryur 2019-06-05 18:13:38 +08:00 via Android @chendy 生成 javadoc 只是第一步，原生的 javadoc 很不便于查询和展示，我是生成了自定义格式的类 javadoc markdown 文件 |
 | 86 guiling 2019-06-05 18:46:34 +08:00 via Android yapi |
 | 87 linvaux 2019-06-05 19:05:00 +08:00 via Android eolinker |
 | 89 yoshiyuki 2019-06-05 19:19:42 +08:00 showdoc |
 | 90 Egfly 2019-06-05 19:21:08 +08:00 via iPhone Yapi |
 | 91 luman 2019-06-05 19:26:38 +08:00 apidoc +1 养成改代码前先改文档注释，再写个自动发布脚本。简直不要太舒服 |
 | 92 zhangtao 2019-06-05 19:43:42 +08:00 yapi +1 |
 | 94 blueorange 2019-06-05 20:33:53 +08:00 swagger-ui.html |
 | 95 newmind 2019-06-05 20:35:04 +08:00 代码即文档 |
 | 96 wc951 2019-06-05 20:35:25 +08:00 via Android spring restdoc，文档片段写在单元测试里 |
 | 97 jiangzhuo 2019-06-05 20:58:58 +08:00 swagger |
 | 98 lygmqkl 2019-06-05 21:54:50 +08:00 postman / showdoc api 文档而已 搞那么复杂干嘛？ 难道你们编程的生活还不够苦难吗？ |
 | 100 changwei 2019-06-05 22:42:57 +08:00 |
Select Language