接口开始使用 Swagger2 生成文档,每个 Controller 都要配一堆注解生成文档,繁琐重复。就比如我写了如下的 Controller:
@Api(tags = "学生接口") @RestController @RequestMapping("web/v1/student") public class StudentController { @ApiOperation("根据编号获取学生信息") @ApiImplicitParams( @ApiImplicitParam(name = "stu_no", value = "学生编号")) @GetMapping("getByNo") public StudentVO getByNO(@RequestParam("stu_no") String stuNo) { StudentVO stu = new StudentVO(); stu.setStuNo(stuNo); stu.setName("张三"); return stu; } @ApiOperation("添加学生信息") @ApiImplicitParams( { @ApiImplicitParam(name = "name", value = "学生名称", defaultValue = "张三"), @ApiImplicitParam(name = "no", value = "学生编号", defaultValue = "std-10001", required = true) } ) @PostMapping("add") public StudentVO addStudent(String name, String no) { StudentVO s = new StudentVO(); s.setName(name); s.setStuNo(no); return s; } }
我觉得更简便的方式是通过注释生成文档,就像这样:
/** * 学生接口 */ @RestController @RequestMapping("web/v1/student") public class StudentController { /** * 根据编号获取学生信息 * @param stuNo 学生编号 */ @GetMapping("getByNo") public StudentVO getByNO(@RequestParam("stu_no") String stuNo) { StudentVO stu = new StudentVO(); stu.setStuNo(stuNo); stu.setName("张三"); return stu; } /** * 添加学生信息 * @param name 学生名称|张三 * @param no 学生编号|required|std-10001 */ @PostMapping("add") public StudentVO addStudent(String name, String no) { StudentVO s = new StudentVO(); s.setName(name); s.setStuNo(no); return s; } }
于是我写了个EasySwagger,只需加个@EnableEasySwagger
开启功能。原理也简单,通过反射修改DocumentationCache
类中的文档信息。
![]() | 1 lyusantu 2020-09-14 09:22:18 +08:00 不用 Swagger,每个 Controller 不还是需要写一堆注释? 看起来不也是重复且行数更长 照这样认为的话,自己完全可以再写一个自定义注解 CustomRestController,把 RestController 和 RequestMapping 整合一下,用起来 @CustomRestController("/web/v1/student")更简单 |
2 Rwing 2020-09-14 09:22:53 +08:00 用注释生成文档竟然不是标准功能。。。。。 |
3 Vkery 2020-09-14 09:30:26 +08:00 用注释的话大家都要用标准的注释模板,而且字段说明和参数示例都得通过统一的格式来写,注释里一般都没有提示容易写错 |
![]() | 4 pushback 2020-09-14 09:32:36 +08:00 所以说反射里面有获取类注释的 |
![]() | 5 anzu 2020-09-14 09:42:36 +08:00 为什么不直接用 @ ApiParam |
![]() | 6 chendy 2020-09-14 09:44:18 +08:00 注释出文档问题不大 出 openapi 格式问题很大,很多东西是覆盖不到的 |
![]() | 7 qwerthhusn 2020-09-14 10:12:38 +08:00 我感觉这个侵入有点烦,还不好生成离线文档,有的生成得文档还不准确,倒不如分开写 |
![]() | 8 zoyua 2020-09-14 10:16:48 +08:00 个人觉得 swagger 注解的内容可以部分替代掉注释 |
![]() | 9 cweijan 2020-09-14 10:33:28 +08:00 这个项目可以满足你的需求 https://github.com/Willing-Xyz/RestDoc |
![]() | 10 NakeSnail 2020-09-14 10:39:33 +08:00 是有点烦,只是标准的注释格式现在的表达能力还不够,到最后还是要自己定义一些格式。Swagger 这方面已经很完善了 |
11 wc951 2020-09-14 10:45:10 +08:00 via Android swagger 侵入性太强,我一般用基于 spring test 的 spring restdocs |
![]() | 12 passerbytiny 2020-09-14 11:03:27 +08:00 via Android 重要的第一点,接口文档是给全体开发人员用的,Javadoc 是给 Java 开发人员用的,这一点不同导致的就是“约定”的不同。 第二点,相比与注解,Javadoc 规则好多年没升级了,而且 Javadoc 是注释不是代码,并不适合自动化处理。Hibernate 、Spring 都已经嫌 @Deprecated 不够用开始自己造仅当标记的注解了。 第三点,严格来说,Controller 中的公开方法,是给框架用的模板,而不是给其他方法调用的 api,给他附加 Javadoc 是不合适的。 解决方案是,接口上不要添加 Javadoc,只用注解。 |
![]() | 13 passerbytiny 2020-09-14 11:15:36 +08:00 via Android ![]() @RequestMapping 、 @EventListerer 、 @Bean 等注解加持的方法,事实上都不是对外 API,都不需要再加 Javadoc 。奈何过不了 Checkstyle,我现在用是统一加“已忽略,请看它的注解”的 Javadoc,不知道有没有更好的方案。 @wc951 这个虽不侵入代码,但侵入开发方式。它主要是接口的测试代码,导出 api 是附带功能,适合测试驱动开发团队,不适合大多数团队。 |
![]() | 14 NeverNot 2020-09-14 11:21:50 +08:00 我现在 觉得 swagger 集成进项目里面 太耦合了,一个 controller 方法,注解 行数比代码行数还多, 打包的时候 多一堆 jar 包,用了 一次 yapi 后,觉得 接口文档 就该和 业务项目分离, 文档是文档 项目是项目,两边清爽 |
15 SD10 2020-09-14 11:25:39 +08:00 via iPhone 一个开发前,一个开发后,目标不一样 |
16 star7th 2020-09-14 11:56:33 +08:00 我觉得 sw 那种方式太侵入代码了,不是一种好方式。当然国外和国内情况有点不一样。 就国内的场景而言,这种方法并不使用广泛。 |
17 star7th 2020-09-14 12:01:55 +08:00 所以我支持了另一种没那么侵入业务代码的注解生成机制: https://www.showdoc.com.cn/page/741656402509783 |
![]() | 18 clf 2020-09-14 12:31:27 +08:00 apidoc,非侵入+注释写文档。 |
![]() | 19 xnotepad 2020-09-14 12:47:41 +08:00 要不要试试 https://apidoc.tools 就是注释写文档,还提供了对 vscode 的插件支持。 |
![]() | 20 JJstyle &nsp; 2020-09-14 13:17:52 +08:00 我都是手写模板,没觉得有多麻烦,这是我 API 模板: https://textit.yeskn.com/b49f63e35a6b09d3d947966cf18a4ef9 |
21 lidlesseye11 2020-09-14 13:34:26 +08:00 我以为一般都是手写 swagger 文档再拿去生成代码(生成的代码应该是和 swagger 没关系的),而不是在代码里写文档去生成 swagger 。。。 (虽然有点儿像鸡生蛋蛋生鸡。。不过这样搞总觉得哪里不对劲儿 |
![]() | 23 balabalaguguji 2020-09-14 17:26:40 +08:00 注释写文档比较麻烦,而且还会把代码弄的乱七八糟一堆额外的东西。 可以试下易文档 https://easydoc.xyz 有专门的 API 文档编辑器,方便很多 看个预览效果:www.easydoc.xyz/s/17790664 |
![]() | 24 liujialongstar 2020-09-14 17:39:43 +08:00 @lyusantu 公司有一项考核指标: 千行代码注释, 如果不用 swagger 正好可以刷指标 |
![]() | 25 zzzmh 2020-09-14 17:48:05 +08:00 apidoc 好像可以满足这个需求 |
![]() | 26 jeffh 2020-09-14 17:50:45 +08:00 yapi 就可以注释生成文档啊 |
![]() | 27 Yuicon 2020-09-14 17:57:26 +08:00 文档就是要耦合 离代码越近越好 文档与代码不一致或者同步不自动化才是大问题 |
28 jiyingze 2020-09-14 18:33:50 +08:00 |
29 lingxi27 2020-09-14 20:49:42 +08:00 swagger 文档>>>代码 |
![]() | 30 ideaa 2020-09-15 09:21:27 +08:00 @cp_api get, /main/index, 获取框架当前版本号 @cp_request t|当前时间|1 php 中我这样实现的,仅支持 GET 请求,地址是 /main/index, 接受当前时间参数 t,不能为空 |
![]() | 31 RandomJoke 2020-09-22 18:35:48 +08:00 我也觉得写注释好,比较纯粹。二次开发了一个 restdoc repo,从 javadoc 生成了文档,apidoc 的话也可以,有点学习成本 |
32 smartdoc647 2021-07-22 22:43:59 +08:00 spring 技术栈 smart-doc+torna 才是王道 |