有什么 Api 文档管理工具具备 Swagger 那样直接用浏览器就能测试接口的能力吗？

一直都是在代码中用注解 /注释直接生成一个 swagger 访问界面，可以直接测试接口，但是时间久了以后，开始意识到别人说的“设计和实现应该是分离的”才是正确的。利用代码中的注解 /注释来生成 swagger 文档有几个难以解决的问题：

*.生成的接口是按照代码分组的；无法按照业务需求组织接口分组，api 使用者均反应翻阅接口时，明明在业务上很内聚的几个接口分布在不同的分组里，查阅不便。
*.无法对接口和参数进行排序。会造成和上面一样的问题
*.对响应结构字段的注释描述不方便，比如在 spring boot 中，就要求你必须使用类作为控制器接口返回的参数类型，在类中使用注解，才能被 swagger 正确识别，而很多项目的序列化都是自定义的，接口直接返回的是序列化后的 String，此时 swagger 就无法识别返回内容中的结构
*.mock 假数据非常困难，造成 api 使用者的对接接口必须等到接口开发差不多了才能对接，效率非常低下。这是很重要的痛点

我最近也找了不少文档管理工具，发现在解决上述问题的时候，他们各有千秋，但是他们产生了一个新问题，就是他们普遍不提供像 swagger 那样，直接在浏览器就可以访问的测试真实接口的页面，要不就是要你下专门的工具，要不就是浏览器要安装特殊插件，还有要你写测试用例导入到 postman 去测试的。。。对于我来说，这太重了。

所以我想找一个折中，我愿意自己写文档来生成一个 api 文档管理页面，但是我希望这个页面除了 mock 以外，可以让我像 swagger 一样测试真实接口。当然如果这玩意是开源，可以自己部署那最好不过

crclz

2021-01-01 19:41:45 +08:00

首先你也意识到了，下面这点是一个痛点。

mock 假数据非常困难，造成 api 使用者的对接接口必须等到接口开发差不多了才能对接，效率非常低下。这是很重要的痛点。

我建议的解决方案是从团队的工作流程入手：

在开发初期就确定接口的格式，然后前后端人员共同进行评审，最终确定接口的格式。这之后就花 1-2 个小时在 springboot 里面把方法和参数都写出来，然后就可以有 swagger 文档供前端拿去用了。另外，swagger 的核心是那个 json 文件，相当于 API 的中间语言表示。那个 json 文件你拿去其他 mock 的框架里面，都是支持导入的。