由于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: 123456spring 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 注解指定模型的相关信息。
主要的注解就是这些了，在使用的过程中可以自己取摸索一下。
当然，我所实现的只是一个最简单的demo。你通过这篇文章可以快速的使用knife4j进行controller接口的测试，这种通过可视化界面的测试能大大减轻我们测试的时间和精力，不用再通过postman进行测试了。
我始终认为官网才是一个技术最权威、最有说服力的地方。我们在使用任何第三方的技术出现了问题都应该先在相应的官网进行查找，如果官网上没有才去其他的渠道。
