有没有觉的 swagger2 注解难用的，用注释生成文档不好么？

V2EX = way to explore

V2EX 是一个关于分享和探索的地方

现在注册

已注册用户请登录

这是一个创建于 1557 天前的主题，其中的信息可能已经有所发展或是发生改变。

接口开始使用 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类中的文档信息。

32 条回复 • 2021-07-22 22:43:59 +08:00

lyusantu

2020-09-14 09:22:18 +08:00

不用 Swagger，每个 Controller 不还是需要写一堆注释？看起来不也是重复且行数更长

照这样认为的话，自己完全可以再写一个自定义注解 CustomRestController，把 RestController 和 RequestMapping 整合一下，用起来 @CustomRestController("/web/v1/student")更简单

Rwing

2020-09-14 09:22:53 +08:00

用注释生成文档竟然不是标准功能。。。。。

Vkery

2020-09-14 09:30:26 +08:00

用注释的话大家都要用标准的注释模板,而且字段说明和参数示例都得通过统一的格式来写,注释里一般都没有提示容易写错

pushback

2020-09-14 09:32:36 +08:00

所以说反射里面有获取类注释的🐎

anzu

2020-09-14 09:42:36 +08:00

为什么不直接用 @ ApiParam

chendy

2020-09-14 09:44:18 +08:00

注释出文档问题不大
出 openapi 格式问题很大，很多东西是覆盖不到的

qwerthhusn

2020-09-14 10:12:38 +08:00

我感觉这个侵入有点烦，还不好生成离线文档，有的生成得文档还不准确，倒不如分开写

zoyua

2020-09-14 10:16:48 +08:00

个人觉得 swagger 注解的内容可以部分替代掉注释

cweijan

2020-09-14 10:33:28 +08:00

这个项目可以满足你的需求
https://github.com/Willing-Xyz/RestDoc

NakeSnail

2020-09-14 10:39:33 +08:00

是有点烦，只是标准的注释格式现在的表达能力还不够，到最后还是要自己定义一些格式。Swagger 这方面已经很完善了

wc951

2020-09-14 10:45:10 +08:00 via Android

swagger 侵入性太强，我一般用基于 spring test 的 spring restdocs

passerbytiny

2020-09-14 11:03:27 +08:00 via Android

重要的第一点，接口文档是给全体开发人员用的，Javadoc 是给 Java 开发人员用的，这一点不同导致的就是“约定”的不同。

第二点，相比与注解，Javadoc 规则好多年没升级了，而且 Javadoc 是注释不是代码，并不适合自动化处理。Hibernate 、Spring 都已经嫌 @Deprecated 不够用开始自己造仅当标记的注解了。

第三点，严格来说，Controller 中的公开方法，是给框架用的模板，而不是给其他方法调用的 api，给他附加 Javadoc 是不合适的。

解决方案是，接口上不要添加 Javadoc，只用注解。

passerbytiny

2020-09-14 11:15:36 +08:00 via Android

@RequestMapping 、 @EventListerer 、 @Bean 等注解加持的方法，事实上都不是对外 API，都不需要再加 Javadoc 。奈何过不了 Checkstyle，我现在用是统一加“已忽略，请看它的注解”的 Javadoc，不知道有没有更好的方案。

@wc951 这个虽不侵入代码，但侵入开发方式。它主要是接口的测试代码，导出 api 是附带功能，适合测试驱动开发团队，不适合大多数团队。