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

[MrXiong]

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

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

[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 回馈社区~~