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

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

passerbytiny

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

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

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

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

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