springboot3整合knife4j实现测试

由于spring boot2与spring boot3版本的巨大差异，整合knife4j的方式也有了很大的不同。本次我同时创建一个spring boot2与spring boot3项目。使用这两个版本来整合knife4j，最终来比较一下这两个版本knife4j的不同之处。

使用spring boot3.1.6整合knife4j；

• SpringBoot3只支持OpenAPI3规范

1、创建spring boot项目并导入knife4j的依赖：

<dependency>
    <groupId>com.github.xiaoymin</groupId>
    <artifactId>knife4j-openapi3-jakarta-spring-boot-starter</artifactId>
    <version>4.3.0</version>
</dependency>

2、其实现在就可以直接使用knife4j了，不需要再做其他的配置；

创建一个controller控制器，完成一些测试：

访问http:localhost:8080/doc.html页面，可以直接看到我们自定义的接口和方法；

这就是spring boot3版本的最大不同，你只要直接引入了knife4j的依赖就可以直接在controller控制器中使用了，而不需要在进行任何的配置；

但是现在我们没有进行任何的属性配置，所以knife4j的页面是初始的页面：

如果你想要进行一些属性的配置，如：作者、版本等可以在配置类中进行实现：

@Configuration
public class Knife4jConfig {

    @Bean
    public OpenAPI springShopOpenAPI() {
        return new OpenAPI()
                // 接口文档标题
                .info(new Info().title("一个API接口文档")
                        // 接口文档简介
                        .description("这是基于Knife4j OpenApi3的测试接口文档")
                        // 接口文档版本
                        .version("1.0版本")
                        // 开发者联系方式
                        .contact(new Contact().name("张乔")
                                .email("000000000@qq.com")))
                .externalDocs(new ExternalDocumentation()
                        .description("SpringBoot3测试knife4j")
                        .url("http://127.0.0.1:8888"));
    }

}

再次启动项目，可以看到主页已经发生了变化

同时，我们也可以在yml配置文件中进行一些knife4j信息的配置：

#springdoc相关配置
springdoc:
  swagger-ui:
    #自定义swagger前端请求路径，输入http：127.0.0.1:8080/swagger-ui.html会自动重定向到swagger页面
    path: /swagger-ui.html
    tags-sorter: alpha
    operations-sorter: alpha
  api-docs:
    path: /v3/api-docs    #swagger后端请求地址
    enabled: true   #是否开启文档功能
  group-configs:
    - group: 'com.hgh.yuzhan'
      paths-to-match: '/**'
      packages-to-scan: com.example.springboot3knife4j   #按包路径匹配:一般到启动类的包名

#knife4j相关配置 可以不用改
knife4j:
  enable: true    #开启knife4j，无需添加@EnableKnife4j注解
  setting:
    language: zh_cn   #中文
  #开启Swagger的Basic认证功能,默认是false
#  basic:
#    enable: true
    # Basic认证用户名
#    username: 张乔
    # Basic认证密码
#    password: 123456

spring boot2.7.17整合knife4j:

创建一个spring boot项目，并导入knife4j的依赖：

<dependency>
    <groupId>com.github.xiaoymin</groupId>
    <artifactId>knife4j-openapi2-spring-boot-starter</artifactId>
    <version>4.3.0</version>
</dependency>

在yml文件中配置一些属性：

knife4j:
  enable: true
  openapi:
    title: 进行测式文档
    description:
    email: 00000000000.com
    concat: 张乔
    url: https://docs.xiaominfo.com
    version: v2.0
    license: Apache 2.0
    license-url: https://stackoverflow.com/
    terms-of-service-url: https://stackoverflow.com/
    group:
      test1:
        group-name: 一个分组
        api-rule: package
        api-rule-resources:
          - com.example.springboot2knife4j

创建一个controller控制类，并启动项目；

可以看到直接主页面就是我们配置的信息，不需要用到配置类；

---

Spwagger2和OpenApi3注解的对应关系

Swagger 2                                                                    OpenAPI 3                                                                                                    注解位置
@Api(tags="接口类描述")                                            @Tag(name = “接口类描述”)                                                          Controller 类上
@ApiOperation(value="接口方法描述")                       @Operation(summary = “接口方法描述”)                                       Controller 方法上
@ApiImplicitParams                                                    @Parameters                                                                                  Controller 方法上        
@ApiImplicitParam                                                    @Parameter(description = “参数描述”)                                            Controller 方法@Parameter里
@ApiParam                                                               @Parameter(description = “参数描述”)                                            Controller 方法的参数上
@ApiIgnore                                                                @Parameter(hidden = true) 或 @Operation(hidden = true)                             -
@ApiModel                                                                 @Schema                                                                                             DTO类上
@ApiModelProperty                                                    @Schema                                                                                                DTO属性上

一些常用注解说明：

@Tag

• 作用范围：操作对象、控制器、模型
• 作用：用于说明或定义的标签。也可以作用于方法上
• 部分参数：
  • name：名称
  • description：描述

@Hidden

• 作用范围：操作对象、实体类属性
• 作用范围：是否在 API 文档中隐藏。

@ApiResponse

• 作用：API 的响应信息。也可以作用于方法上，一般常用于方法上

@Schema
用于描述实体类属性的描述、示例、验证规则等，比如 POJO 类及属性。

部分参数：

name：名称
title：标题
description：描述
example：示例值
required：是否为必须
format：属性的格式。如 @Schema(format = “email”)
maxLength 、 minLength：指定字符串属性的最大长度和最小长度
maximum 、 minimum：指定数值属性的最大值和最小值
pattern：指定属性的正则表达式模式
type： 数据类型

示例如下：

@Tag(name = "用户", description = "用户交互载体")
@Data
public class User {

    @Schema(name = "用户id", type = "string")
    private String id;
    @Schema(name = "用户名", type = "string")
    private String name;
    @Schema(name = "密码", type = "string")
    private String password;
}

@Operation
描述 API 操作的元数据信息。常用于 controller 上

部分参数：

summary：简短描述
description ：更详细的描述
hidden：是否隐藏
tags：标签，用于分组API
operationId：操作的唯一标识符，建议使用唯一且具有描述性的名称
parameters：指定相关的请求参数，使用 @Parameter 注解来定义参数的详细属性。
requestBody：指定请求的内容，使用 @RequestBody 注解來指定请求的类型。
responses：指定操作的返回内容，使用 @ApiResponse 注解定义返回值的详细属性

@Parameter
用于描述 API 操作中的参数

部分参数：

name : 指定的参数名
in：参数来源，可选 query、header、path 或 cookie，默认为空，表示忽略
ParameterIn.QUERY 请求参数
ParameterIn.PATH 路径参数
ParameterIn.HEADER header参数
ParameterIn.COOKIE cookie 参数
description：参数描述
required：是否必填，默认为 false
schema ：参数的数据类型。如 schema = @Schema(type = “string”)

@Parameters

包含多个 @Parameter 注解，指定多个参数。示例代码如下：

@Parameters({@Parameter(name = "name",description = "姓名",required = false),
            @Parameter(name = "age",description =  "年龄",required = true)})

@RequestBody
API 请求的注解

description：请求信息的描述
content：请求的内容
required：是否必须

@Content
内容注解。

部分参数：

mediaType：内容的类型。比如：application/json
schema：内容的模型定义，使用 @Schema 注解指定模型的相关信息。

主要的注解就是这些了，在使用的过程中可以自己取摸索一下。