[Java知识库]swagger2文档基于knife4j 2.0.5二次封装工具

介绍

在之前两篇博客的基础上：https://blog.csdn.net/Vampire_1122/article/details/120378205、https://www.kangaroohy.com/2022/02/15/knife4j-swagger-api.html

将相关的配置封装成spring boot starter，默认扫描@Api注解，因此引入相关包以后，只需要在controller上加上@Api注解即可

当然，也支持通过包路径扫描，配置上相关的分组信息即可

Maven

源码已上传GitHub：https://github.com/kangaroo1122/swagger-spring-boot-starter

目前已上传至maven中央仓库，当前最新版本：1.0.0

或查看这个地址找到最新版本：https://search.maven.org/artifact/com.kangaroohy/swagger-spring-boot-starter

<dependency>
  <groupId>com.kangaroohy</groupId>
  <artifactId>swagger-spring-boot-starter</artifactId>
  <version>1.0.0</version>
</dependency>

使用

引入pom.xml后，若要更新配置信息，查看yml提示，完整配置如下

访问地址：http://localhost:{port}/doc.html

认证访问

kangaroohy:
  swagger:
    certifiable: true
    username: admin # 默认admin
    password: 123321 # 默认123321

生产屏蔽

kangaroohy:
  swagger:
    prod: true

默认扫描@Api注解会生成两个分组

• 默认分组-需认证
• 默认分组-无认证

可配置正则调整匹配条件

kangaroohy:
  swagger:
    anon: '^.*/pub/.*$'
    authc: '^((?!/pub/).)*$'

如果需要通过包路径扫描接口，则新增一下配置，如：

kangaroohy:
  swagger:
    group:
      - group-name: 分组一
        apis: com.kangaroohy.controller.auth
        certifiable: true
      - group-name: 分组二
        apis: com.kangaroohy.controller.pub
        certifiable: false

此时，显示的分组会新增以下两个

• 分组一-需认证
• 分组二-无认证

分组校验

此工具集成了几个参数校验的类，由于分组插件有调用相关的类，因此直接放到了这个工具类里

新增或编辑接口，实体分组显示

controller层入参上添加分组信息，如：

新增：ValidGroup.Create.class

public RestResult<String> insertUser(@RequestBody @Validated(ValidGroup.Create.class) UserBO user) {
        return usersService.insertUser(user);
        }

编辑：ValidGroup.Update.class

public RestResult<String> updateUser(@RequestBody @Validated(ValidGroup.Update.class) UserBO user) {
        return usersService.updateUser(user);
        }

入参实体中：

public class UserBO implements Serializable {
    private static final long serialVersionUID = 5699245096095831445L;

    @ApiModelProperty(value = "ID")
    @Null(groups = ValidGroup.Create.class)
    @NotNull(groups = ValidGroup.Update.class, message = "ID不可为空")
    private Long id;
}

此时，在swagger文档上，新增则不会显示ID字段，更新则会显示ID字段