这是一个创建于 2955 天前的主题，其中的信息可能已经有所发展或是发生改变。
- 公司准备使用 swagger，基于注解的方式，但是发现多个项目无法集成，很不方便
- swagger-ui 中没有接口的搜索功能
请问各位还有啥比较好用的轮子？
第1 条附言 2017-09-12 20:39:50 +08:00
@All 各位别搞我啊，得讲道理，我就不信大公司也是口口相传的？
第 2 条附言 2017-09-13 18:17:44 +08:00
看到各位的回复，我也是放心了！当我在接手别人代码的时候的心情也能平复下了！
119 条回复 2018-11-29 20:23:15 +08:00
 | 1 byuc 2017-09-12 19:53:08 +08:00 口口相传 |
 | 2 qinxi 2017-09-12 19:53:50 +08:00 |
 | 3 yoa1q7y 2017-09-12 19:56:25 +08:00 口口相传+1 |
 | 4 sudoz 2017-09-12 19:56:51 +08:00 confluence |
 | 5 Hypn0s 2017-09-12 19:59:42 +08:00 confluence + 1 |
 | 6 gaayyy 2017-09-12 20:03:59 +08:00 靠猜 |
 | 7 ZeoKarl 2017-09-12 20:04:10 +08:00 给你一个眼神,自己体会. |
 | 8 fengxuejianshi 2017-09-12 20:18:15 +08:00 via iPhone 意念 |
 | 9 aaxcc 2017-09-12 20:33:59 +08:00 via iPhone 当然是打印出来贴在公司大门上，每天程序猿进门背一个借口，背错的扣工资 |
 | 10 cutlove 2017-09-12 20:43:57 +08:00 apizza |
 | 11 irgil 2017-09-12 20:45:40 +08:00 swagger，或者公司自研的。 |
 | 12 orancho 2017-09-12 20:47:17 +08:00 protobuf / grpc 的 proto 文件 |
 | 15 AndyJia 2017-09-12 22:23:45 +08:00 via Android openapi |
 | 16 gemini 2017-09-12 22:29:09 +08:00 word 文档不挺好的么 |
 | 17 iyaozhen 2017-09-12 22:30:12 +08:00 via Android wiki，先定接口再开发 |
 | 18 crossoverJie 2017-09-12 22:31:43 +08:00 之前 confluence 现在 swagger |
 | 19 hasbug 2017-09-12 22:43:24 +08:00 口口相传+1 |
 | 20 m939594960 2017-09-12 22:44:40 +08:00 gitlab 的 wiki 功能 |
 | 21 xiaolanglang 2017-09-12 23:13:16 +08:00 口口相传 |
 | 22 fbzl 2017-09-13 00:15:48 +08:00 via iPhone 口口相传，心灵感应 |
 | 23 lgh 2017-09-13 00:28:47 +08:00 via iPhone @orancho #12 顺便问个相关的问题：pb 只能体现接口报文格式，你们是怎样管理 pb 和实际接口之间的关联关系这些信息的？ |
 | 24 Jackeriss 2017-09-13 01:02:57 +08:00 via iPhone 这个全看悟性 |
 | 25 junbguistar 2017-09-13 01:12:15 +08:00 接口多就自己搭 wiki 和 swagger 少就口口相传 |
 | 26 49degree 2017-09-13 01:13:42 +08:00 RAP |
 | 27 fan123199 2017-09-13 01:14:59 +08:00 word 文档 |
 | 28 Lucups 2017-09-13 01:19:33 +08:00 不同方式的文档都有各自的优劣和使用场景，我主要考虑沟通成本，哪种方式沟通成本小用哪种。 目前在公司用 confluence 手写，一个接口一个页面，其他部门人来要时直接丢链接。 PS：Swagger 默认的 UI 不是很好用。有同感的可以考虑这个项目 https://github.com/jensoleg/swagger-ui。 |
| 29 Lucups 2017-09-13 01:20:18 +08:00 |
 | 30 Tyrion 2017-09-13 02:12:31 +08:00 confluence + 1 |
 | 31 bombless 2017-09-13 02:24:17 +08:00 via Android 写代码注释里面的，靠自觉，很多人不写的。 听说大公司都是靠口口相传 |
 | 32 feiyuanqiu 2017-09-13 03:18:32 +08:00 via Android @Lucups 我最近刚好在改这个 ui。它有个问题是把接口参数放在 div 的属性里，导致没法选择及复制，而且参数名长一点的话就显示不全。另外我也不太喜欢它调用接口时单独弹出一个 modal 的方式 |
 | 33 msg7086 2017-09-13 07:33:02 +08:00 早已失传…… |
 | 34 motai 2017-09-13 08:13:53 +08:00 via iPhone rap，word，内部的 wiki 系统 |
 | 35 xtaxcy 2017-09-13 08:18:46 +08:00 via Android 小幺鸡 |
 | 36 caijihui11 2017-09-13 08:37:49 +08:00 apidoc |
 | 37 NSAtools 2017-09-13 08:39:03 +08:00 口口相传 |
 | 38 icycai 2017-09-13 08:53:06 +08:00 via Android 口口相传+1 |
 | 39 kindjeff 2017-09-13 08:57:43 +08:00 via iPhone 传嫡不传庶，传长不传幼，传男不传女 |
 | 40 justicelove 2017-09-13 09:01:48 +08:00 搜索就是 control + F |
 | 41 caizhendi 2017-09-13 09:13:38 +08:00 后台自己维护个文档 |
 | 42 cnbattle 2017-09-13 09:15:02 +08:00 口口相传.gif |
 | 43 simonlu9 2017-09-13 09:16:24 +08:00 eo-linker |
 | 44 chocotan 2017-09-13 09:17:18 +08:00 一开始是口口相传，自从搭了 confluence 后大多用这个了 |
 | 45 Clarencep 2017-09-13 09:19:11 +08:00 我司是我自己用 Laravel 写了一个基于 Markdown 的文档系统，支持文档模版，支持复制粘贴图片，支持全文检索，支持用户权限管理。开发用时约 3 天。 话说这种东西还是自己做的用着舒服：） 上家用的 confluence 也很不错，不过现在这家没买，懒得搞破解版，所以还是自己动手丰衣足食。 |
 | 46 lrh3321 2017-09-13 09:20:48 +08:00 口口相传+1 忘记了就去看聊天记录 |
 | 47 timelessg 2017-09-13 09:29:45 +08:00 via Android 当然是微信了 |
 | 50 keepcleargas 2017-09-13 10:35:01 +08:00 slate + git |
 | 51 xiaowangge 2017-09-13 10:40:27 +08:00 口口相传+聊天记录 +1  |
 | 52 vjnjc 2017-09-13 10:40:29 +08:00 wiki +1 swagger 的话不用他一整套不方便吧，还不如 wiki 上格式写规范点 |
 | 53 teaaa 2017-09-13 10:43:50 +08:00 wiki +1 强迫症觉得必须有统一的接口文档啊 很方便高效啊 要不怎么推锅 |
 | 54 WendellSun 2017-09-13 10:44:11 +08:00 口口相传+1 |
 | 55 noNOno 2017-09-13 10:45:55 +08:00 confluence + 1 |
 | 56 imherer 2017-09-13 10:46:18 +08:00 https://github.com/lord/slate 这个。支持搜索 |
 | 57 codeyung 2017-09-13 10:47:41 +08:00 confluence 自写（之前项目都是自己 wiki 手写的 很多 ） 现在的 swagger 做模块服务时候用 |
 | 58 fork3rt 2017-09-13 10:51:51 +08:00 swagger 或者 手写 markdown |
 | 59 liuqitoday 2017-09-13 11:20:08 +08:00 口口相传+1 |
 | 60 YiBaZhuangYuan 2017-09-13 11:22:50 +08:00 GitLab |
 | 61 my3157 2017-09-13 11:24:23 +08:00 昨天正好也在看这个, 转了一圈, 目前做 api 文档管理的有 nei easyapi eolinker apizza RAP , 体验了其中 eolinker 和 apizza, 最后选择了 postman, 不但能做文档, 顺便还写了 api 测试 , 免费档已够用 |
 | 62 lifeforwater 2017-09-13 11:31:41 +08:00 小幺鸡 |
 | 63 zjsxwc 2017-09-13 11:33:51 +08:00 via Android 邮件 |
 | 64 xxdd 2017-09-13 11:44:08 +08:00 看我口型 |
| 65 orancho 2017-09-13 11:53:53 +08:00 @lgh 如果你用 gRPC 的话，可以直接将 proto 文件中定义的 service 名传给 invoke 函数。对于使用 protobuf 的 RESTful API，我司一般的方法是在对应的 message 前的注释中写上对应的 URI。 |
 | 66 leaybc 2017-09-13 11:58:02 +08:00 我在用 swagger 然后配合第三方的 UI . 感觉挺好的 |
 | 67 silov 2017-09-13 12:01:18 +08:00 markdown 丢 git 上 == |
 | 68 Simcyber 2017-09-13 12:30:31 +08:00 口口相传+1024 |
 | 70 ezreal 2017-09-13 12:52:06 +08:00 via iPhone 口口相传 |
 | 71 laudukang 2017-09-13 13:00:38 +08:00 口口相传 |
 | 72 Vindroid 2017-09-13 13:02:24 +08:00 GitLab |
 | 73 qscqesze 2017-09-13 13:03:48 +08:00 口口相传，最多写个 wiki 解释一下 |
 | 74 zhygkx 2017-09-13 13:06:48 +08:00 |
 | 75 dreamwar 2017-09-13 13:08:49 +08:00 心灵感应 |
 | 76 owenliang 2017-09-13 13:09:46 +08:00 gitlab README |
 | 77 c0878 2017-09-13 13:12:23 +08:00 mkdocs |
 | 78 l00t 2017-09-13 13:17:19 +08:00 Excel + svn |
 | 79 siteshen 2017-09-13 13:27:44 +08:00 我们公司使用的 swagger，不过默认的“先设计好 *所有* API 格式，再生成代码模版”的方式并不适合我们（因为随时需要增加新的 API 和扩展现有的 API ），我们的使用方式如下： 1. python/go 代码按正常逻辑写，如： // method, url, input format, output format routes = [("POST", "/me/update", UpdateMeForm, MeResponse, ["tag1", "tag2", ...])] 2. 自定义函数 ToSwaggerJSON(method, url, request_form, response_object) 生成对应的 swagger.json 文件，然后交给 swagger-ui 处理其余事情； 3. 客户端在浏览器查看 API 文档，几乎没有进行过 API 问题的沟通。 ps: 最大的难点在于 ToSwagger() 函数，python/go 都没找到合适的库，花了不少的时间（印象中 python/go 各一周？），自己查看 swagger 文档实现了部分接口格式。 |
| 80 Lucups 2017-09-13 13:29:52 +08:00 @feiyuanqiu 改好了提 pull request 回馈社区~~ |
 | 81 mahengyang 2017-09-13 13:56:00 +08:00 多个接口之间的关系怎么体现呢？ |
 | 82 rb6221 2017-09-13 14:00:09 +08:00 RAP 啊 |
 | 83 luili 2017-09-13 14:02:37 +08:00 confluence |
 | 84 tjxiter 2017-09-13 14:08:48 +08:00 口口相传+1 |
 | 85 darklh 2017-09-13 14:27:13 +08:00 前公司用 rap |
 | 86 zpf124 2017-09-13 14:29:49 +08:00 前段时间我们要补文档，找了半天最终用了 swagger。 话说当时还看到一个 Read The Docs 不知道有没有人用这个 |
 | 87 acros 2017-09-13 14:34:11 +08:00 口口相传的各位 兼职公司吟游诗人职位吗？ |
 | 88 JustCJ 2017-09-13 14:45:34 +08:00 slate |
 | 89 MushishiXian 2017-09-13 15:14:21 +08:00 有时候更新了文档还是要去通知下,通知过程中可能就直接说改了哪里,也可能就是口口相传了,网易那个 nei 不知道怎样,体验了下感觉还行 |
 | 90 v2chou 2017-09-13 15:15:06 +08:00 给你一个眼神,自己体会 |
 | 91 zhouyou457 2017-09-13 15:20:30 +08:00 正常情况下写 md，然后导出 pdf 放 svn 上。。 紧急情况下，口口相传，记不清的自己看聊天记录[doge] |
 | 93 xjmroot 2017-09-13 15:30:55 +08:00 showdoc 管理的，蛮方便 https://www.showdoc.cc/1666386?page_id=15335212 |
| 94 xjmroot 2017-09-13 15:32:40 +08:00  1 公司内部部署个，超级简单，还能导出 word https://github.com/star7th/showdoc |
| 95 teaaa 2017-09-13 15:36:45 +08:00 dokuwiki 也很好用啊 可以自动生成目录 |
 | 96 Wysten 2017-09-13 15:36:59 +08:00 眼神体会 |
 | 97 kk941kk 2017-09-13 15:43:53 +08:00 没有文档，不用管理。。 |
 | 98 jadec0der 2017-09-13 16:37:12 +08:00 thrift / confluence ( http) |
 | 99 SvenWong 2017-09-13 16:41:04 +08:00 口口相传 +1 |
 | 100 Hilong 2017-09-13 16:41:59 +08:00 via Android 300 多个接口，没有文档，就一个 postman 调用事例，然后口口相传 |
Select Language