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.kangaroohygroupId>
  <artifactId>swagger-spring-boot-starterartifactId>
  <version>1.0.0version>
dependency>
1
2
3
4
5

使用

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

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

认证访问

kangaroohy:
  swagger:
    certifiable: true
    username: admin # 默认admin
    password: 123321 # 默认123321
1
2
3
4
5

生产屏蔽

kangaroohy:
  swagger:
    prod: true
1
2
3

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

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

可配置正则调整匹配条件

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

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

kangaroohy:
  swagger:
    group:
      - group-name: 分组一
        apis: com.kangaroohy.controller.auth
        certifiable: true
      - group-name: 分组二
        apis: com.kangaroohy.controller.pub
        certifiable: false
1
2
3
4
5
6
7
8
9

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

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

枚举展示，类注解@ApiModelEnum

• 1、属性上必须要有@ApiModelProperty注解
• 2、如果字段的属性不是枚举，但是是枚举映射，如：1男，0女，可以设置@ApiModelProperty注解的nodes值为枚举的全路径，如：com.kangaroohy.GenderEnum
• 3、重写枚举的toString()方法可以改变展示的值

枚举

@ApiModelEnum
@Getter
public enum GenderEnum {
    MALE(0, "男"),
    FEMALE(1, "女"),
    UNKNOWN(2, "未知");
    private final Integer code;
    private final String desc;
    GenderEnum(Integer code, String desc) {
        this.code = code;
        this.desc = desc;
    }
    /**
     * 单个枚举的展示，不重写默认展示为 name()
     */
    @Override
    public String toString() {
        return code + "-" + desc;
    }
}
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20

使用

@Data
public class UserVo {
    @ApiModelProperty("用户名")
    private String username;
    /**
     * notes 是对应枚举类的全限定名
     */
    @ApiModelProperty(value = "性别", notes = "com.kangaroohy.GenderEnum")
    private Integer gender;
    
    @ApiModelProperty(value = "性别")
    private GenderEnum genderEnum;
}
1
2
3
4
5
6
7
8
9
10
11
12
13

展示如下

分组校验

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

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

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

新增：ValidGroup.Create.class

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

编辑：ValidGroup.Update.class

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

入参实体中：

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;
}
1
2
3
4
5
6
7
8

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