请问各位，公司内部的接口文档是怎么管理的？

[MrXiong]

1. 公司准备使用 swagger，基于注解的方式，但是发现多个项目无法集成，很不方便
2. swagger-ui 中没有接口的搜索功能

请问各位还有啥比较好用的轮子？

@All 各位别搞我啊，得讲道理，我就不信大公司也是口口相传的？

看到各位的回复，我也是放心了！当我在接手别人代码的时候的心情也能平复下了！

[byuc]

口口相传

[qinxi]

https://app.swaggerhub.com/ 这个?

[yoa1q7y]

口口相传+1

[sudoz]

confluence

[Hypn0s]

confluence + 1

[gaayyy]

靠猜

[ZeoKarl]

给你一个眼神,自己体会.🌚

[fengxuejianshi]

意念

[aaxcc]

当然是打印出来贴在公司大门上，每天程序猿进门背一个借口，背错的扣工资

[cutlove]

apizza

[irgil]

swagger，或者公司自研的。

[orancho]

protobuf / grpc 的 proto 文件

[MrXiong]

@irgil swagger 有什么使用姿势

[irgil]

@MrXiong 主要是自动生成文档，自动生成代码

[AndyJia]

openapi

[gemini]

word 文档不挺好的么

[iyaozhen]

wiki，先定接口再开发

[crossoverJie]

之前 confluence 现在 swagger

[hasbug]

口口相传+1

[m939594960]

gitlab 的 wiki 功能

[xiaolanglang]

口口相传

[fbzl]

口口相传，心灵感应

[lgh]

@orancho #12 顺便问个相关的问题：pb 只能体现接口报文格式，你们是怎样管理 pb 和实际接口之间的关联关系这些信息的？

[Jackeriss]

这个全看悟性

[junbguistar]

接口多就自己搭 wiki 和 swagger 少就口口相传

[49degree]

RAP

[fan123199]

word 文档

[Lucups]

不同方式的文档都有各自的优劣和使用场景，我主要考虑沟通成本，哪种方式沟通成本小用哪种。
目前在公司用 confluence 手写，一个接口一个页面，其他部门人来要时直接丢链接。

PS：Swagger 默认的 UI 不是很好用。有同感的可以考虑这个项目 https://github.com/jensoleg/swagger-ui。

[Lucups]

我晕，加了空格还是把句号和链接合在一起了。。。重新补一下:

https://github.com/jensoleg/swagger-ui

[Tyrion]

confluence + 1

[bombless]

写代码注释里面的，靠自觉，很多人不写的。

听说大公司都是靠口口相传

[feiyuanqiu]

@Lucups 我最近刚好在改这个 ui。它有个问题是把接口参数放在 div 的属性里，导致没法选择及复制，而且参数名长一点的话就显示不全。另外我也不太喜欢它调用接口时单独弹出一个 modal 的方式

[msg7086]

早已失传……

[motai]

rap，word，内部的 wiki 系统

[xtaxcy]

小幺鸡

[caijihui11]

apidoc

[NSAtools]

口口相传

[icycai]

口口相传+1

[kindjeff]

传嫡不传庶，传长不传幼，传男不传女

[justicelove]

搜索就是 control + F

[caizhendi]

后台自己维护个文档

[cnbattle]

口口相传.gif

[simonlu9]

eo-linker

[chocotan]

一开始是口口相传，自从搭了 confluence 后大多用这个了

[Clarencep]

我司是我自己用 Laravel 写了一个基于 Markdown 的文档系统，支持文档模版，支持复制粘贴图片，支持全文检索，支持用户权限管理。开发用时约 3 天。

话说这种东西还是自己做的用着舒服：）

上家用的 confluence 也很不错，不过现在这家没买，懒得搞破解版，所以还是自己动手丰衣足食。

[lrh3321]

口口相传+1

忘记了就去看聊天记录

[timelessg]

当然是微信了

[vlean]

@49degree RAP+1 +wiki

[a7063888]

@lrh3321
口口相传+聊天记录 还是老哥稳

公司用 confluence

[keepcleargas]

slate + git

[xiaowangge]

口口相传+聊天记录

+1

[vjnjc]

wiki +1
swagger 的话不用他一整套不方便吧，还不如 wiki 上格式写规范点

[teaaa]

wiki +1
强迫症觉得必须有统一的接口文档啊
很方便高效啊
要不怎么推锅

[WendellSun]

口口相传+1

[noNOno]

confluence + 1

[imherer]

https://github.com/lord/slate 这个。支持搜索

[codeyung]

confluence 自写（之前项目都是自己 wiki 手写的 很多 ） 现在的 swagger 做模块服务时候用

[fork3rt]

swagger 或者 手写 markdown

[liuqitoday]

口口相传+1

[YiBaZhuangYuan]

GitLab

[my3157]

昨天正好也在看这个, 转了一圈, 目前做 api 文档管理的有 nei easyapi eolinker apizza RAP , 体验了其中 eolinker 和 apizza, 最后选择了 postman, 不但能做文档, 顺便还写了 api 测试 , 免费档已够用

[lifeforwater]

小幺鸡

[zjsxwc]

邮件

[xxdd]

看我口型

[orancho]

@lgh

如果你用 gRPC 的话，可以直接将 proto 文件中定义的 service 名传给 invoke 函数。对于使用 protobuf 的 RESTful API，我司一般的方法是在对应的 message 前的注释中写上对应的 URI。

[leaybc]

我在用 swagger 然后配合第三方的 UI . 感觉挺好的

[silov]

markdown 丢 git 上 ==

[Simcyber]

口口相传+1024

[MrXiong]

@leaybc 有啥 ui 推荐

[ezreal]

口口相传

[laudukang]

口口相传

[Vindroid]

GitLab

[qscqesze]

口口相传，最多写个 wiki 解释一下

[zhygkx]

http://springfox.github.io/springfox/

[dreamwar]

心灵感应

[owenliang]

gitlab README

[c0878]

mkdocs

[l00t]

Excel + svn

[siteshen]

我们公司使用的 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 文档实现了部分接口格式。

[Lucups]

@feiyuanqiu 改好了提 pull request 回馈社区~~

[mahengyang]

多个接口之间的关系怎么体现呢？

[rb6221]

RAP 啊

[luili]

confluence

[tjxiter]

口口相传+1

[darklh]

前公司用 rap

[zpf124]

前段时间我们要补文档，找了半天最终用了 swagger。

话说当时还看到一个 Read The Docs 不知道有没有人用这个

[acros]

口口相传的各位····
兼职公司吟游诗人职位吗？

[JustCJ]

slate

[MushishiXian]

有时候更新了文档还是要去通知下,通知过程中可能就直接说改了哪里,也可能就是口口相传了,网易那个 nei 不知道怎样,体验了下感觉还行

[v2chou]

给你一个眼神,自己体会

[zhouyou457]

正常情况下写 md，然后导出 pdf 放 svn 上。。

紧急情况下，口口相传，记不清的自己看聊天记录[doge]

[ming7435]

@49degree RAP+1

[xjmroot]

showdoc 管理的，蛮方便
https://www.showdoc.cc/1666386?page_id=15335212

[xjmroot]

公司内部部署个，超级简单，还能导出 word
https://github.com/star7th/showdoc

[teaaa]

dokuwiki 也很好用啊 可以自动生成目录

[Wysten]

眼神体会

[kk941kk]

没有文档，不用管理。。

[jadec0der]

thrift / confluence ( http)

[SvenWong]

口口相传 +1

[Hilong]

300 多个接口，没有文档，就一个 postman 调用事例，然后口口相传