swagger2文档基于knife4j 2.0.5二次封装工具

原创已于 2024-08-16 18:19:07 修改 · 720 阅读

0 ·

CC 4.0 BY-SA版权

文章标签：

#spring boot #swagger2 #knife4j

于 2022-09-10 21:22:11 首次发布

spring boot 专栏收录该内容

20 篇文章

订阅专栏

本文介绍了一种基于Swagger2和Knife4j的二次封装工具，该工具简化了API文档的生成过程。通过Spring Boot Starter的形式提供，只需在Controller上添加@Api注解即可自动生成文档。支持认证访问及生产环境屏蔽等功能。

介绍

在之前两篇博客的基础上：https://blog.youkuaiyun.com/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;
}