SpringBoot3整合Knife4j4.x版本(Swagger3、OpenApi3)

前言

适用于：SpringBoot 3.x版本

1、为什么使用Knife4j

在前后端分离的开发模式下，后端人员开发完接口后，需要单独出一份文档，说明每个接口的作用以及接口的传入参数与响应参数；但是项目处于快速开发阶段时，就会出现文档更新不及时的情况，久而久之在对接接口时就会出现效率下降的情况，Knife4j提供一个可视化的UI界面，通过Knife4j只需要注解就可以向前端暴漏出所有的接口信息，便于前端对接以及对系统的测试。页面访问方式为：ip:prot/context-path/doc.html

2、基本使用

2.1 pom

        <dependency>
            <groupId>com.github.xiaoymingroupId>
            <artifactId>knife4j-openapi3-jakarta-spring-boot-starterartifactId>
            <version>4.4.0version>
        dependency>
1
2
3
4
5

2.2 配置Knife4j

创建配置文件：Knife4jConfig

@Configuration
public class SwaggerConfig {
    @Bean
    public OpenAPI customOpenAPI() {
        return new OpenAPI()
                .info(new Info()
                        .title("XXX系统API")
                        .version("1.0")
                        .description("Knife4j集成接口文档")
                        .termsOfService("http://www.lhz.com")
                        .license(new License().name("Apache 2.0")));
    }
}
1
2
3
4
5
6
7
8
9
10
11
12
13

yaml

# springdoc-openapi项目配置
springdoc:
  swagger-ui:
    path: /swagger-ui.html
    # 排序方式为首字母
    tags-sorter: alpha
    # 使用增强order属性进行排序，或者不设置该参数( @ApiOperationSupport(order = n)直接生效)
    operations-sorter: order
  api-docs:
    path: /v3/api-docs
  group-configs:
    - group: '测试'
      paths-to-match: '/**'
      # controller所在包
      packages-to-scan: com.lhz.demo.controller.swagger3

# knife4j的增强配置，不需要增强可以不配
knife4j:
  enable: true
  setting:
    language: zh_cn
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21

2.3 拦截器放行

如果项目中配置了拦截器，那么会拦截Knife4j的请求的资源，需要进行放行处理，放行的url如下：

• “/swagger-resources/**”
• “/doc.html”
• “/swagger-ui.html”
• “/v2/**”
• “/v3/**”
• “/webjars/**”

2.4 实体类

创建一个实体类

@Data
@Schema(description = "测试实体类")
public class TestEntity {

    @Schema(description = "名称", requiredMode = Schema.RequiredMode.REQUIRED)
    private String name;

    @Schema(description = "手机号")
    private String phone;
}
1
2
3
4
5
6
7
8
9
10

2.5 SpringBoot整合基础使用

2.5.1 基础配置

通过@Tag注解，为当前Controller进行命名，通过@Operation为Controller中的方法设置名称

@Tag(name = "XX接口管理")
@RestController
public class TestController {

    @Operation(summary = "测试方法", description = "测试方法")
    @GetMapping("/test")
    public void test() {
        System.out.println("进入了test接口");
    }
}
1
2
3
4
5
6
7
8
9
10

2.5.2 Post(实体)请求

和传统的Post请求写法一致参数加上@RequestBody注解，通过@Operation为接口命名

Controller：

@Tag(name = "XX接口管理")
@RestController
public class TestController {

    @Operation(summary = "测试方法", description = "测试")
    @PostMapping("/test")
    public void test(@RequestBody TestEntity test) {
        System.out.println("test = " + test);
    }
}
1
2
3
4
5
6
7
8
9
10

文档页面：

调试页面：

2.5.3 Get(实体)请求

对于Get请求时，需要加一个由springdoc提供的注解@ParameterObject

@Tag(name = "XX接口管理")
@RestController
public class TestController {

    @Operation(summary = "测试Get请求", description = "测试")
    @GetMapping("/testGet")
    public void testGet(@ParameterObject TestEntity test) {
        System.out.println("test = " + test);
    }
    
}
1
2
3
4
5
6
7
8
9
10
11

文档页面：

调试页面：
可以看到Get请求的请求参数形式是以列表的形式进行呈现，而Post的请求参数是json形式

2.5.4 响应参数配置

对于返回对象，我们通常可以为某个具体的Object或者List