这是一个创建于 1204 天前的主题,其中的信息可能已经有所发展或是发生改变。
一直都是在代码中用注解 /注释直接生成一个 swagger 访问界面,可以直接测试接口,但是时间久了以后,开始意识到别人说的“设计和实现应该是分离的”才是正确的。利用代码中的注解 /注释来生成 swagger 文档有几个难以解决的问题:
*.生成的接口是按照代码分组的;无法按照业务需求组织接口分组,api 使用者均反应翻阅接口时,明明在业务上很内聚的几个接口分布在不同的分组里,查阅不便。
*.无法对接口和参数进行排序。会造成和上面一样的问题
*.对响应结构字段的注释描述不方便,比如在 spring boot 中,就要求你必须使用类作为控制器接口返回的参数类型,在类中使用注解,才能被 swagger 正确识别,而很多项目的序列化都是自定义的,接口直接返回的是序列化后的 String,此时 swagger 就无法识别返回内容中的结构
*.mock 假数据非常困难,造成 api 使用者的对接接口必须等到接口开发差不多了才能对接,效率非常低下。这是很重要的痛点
我最近也找了不少文档管理工具,发现在解决上述问题的时候,他们各有千秋,但是他们产生了一个新问题,就是他们普遍不提供像 swagger 那样,直接在浏览器就可以访问的测试真实接口的页面,要不就是要你下专门的工具,要不就是浏览器要安装特殊插件,还有要你写测试用例导入到 postman 去测试的。。。对于我来说,这太重了。
所以我想找一个折中,我愿意自己写文档来生成一个 api 文档管理页面,但是我希望这个页面除了 mock 以外,可以让我像 swagger 一样测试真实接口。当然如果这玩意是开源,可以自己部署那最好不过
4 条回复 • 2021-01-02 14:19:03 +08:00
|
|
2
crclz 2021-01-01 19:41:45 +08:00 1
首先你也意识到了,下面这点是一个痛点。
mock 假数据非常困难,造成 api 使用者的对接接口必须等到接口开发差不多了才能对接,效率非常低下。这是很重要的痛点。
我建议的解决方案是从团队的工作流程入手:
在开发初期就确定接口的格式,然后前后端人员共同进行评审,最终确定接口的格式。这之后就花 1-2 个小时在 springboot 里面把方法和参数都写出来,然后就可以有 swagger 文档供前端拿去用了。另外,swagger 的核心是那个 json 文件,相当于 API 的中间语言表示。那个 json 文件你拿去其他 mock 的框架里面,都是支持导入的。
|
|
|
3
lry 2021-01-01 20:56:55 +08:00
Spring REST Docs 通过写测试用例的方式生成文档
|