1、SpringBoot3整合Knif4j

1、SpringBoot3整合 knif4j

Knife4j官网地址

快速整合

1、添加依赖

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

2、添加配置

knife4j:
  enable: true
  openapi:
    title: Knife4j官方文档
    description: "`我是测试`,**你知道吗**
    # aaa"
    email: katherine@foxmail.com
    concat: katherine
    url: https://docs.xiaominfo.com
    version: v4.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.knife4j.demo.new3

OpenApi3的规范

提示

• SpringBoot3只支持OpenAPI3规范

Spwagger2和OpenApi3注解的对应关系

对应关系为：

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

注解说明

@Tag

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

@Hidden

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

@ApiResponse

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

部分参数：

responseCode：响应的 HTTP 状态码
description：响应信息的描述
content：响应的内容
代码参考：

@ApiResponse(responseCode = "200", description = "查询成功", content = @Content(schema = @Schema(implementation = User.class)))
@ApiResponse(responseCode = "404", description = "查询失败")
@GetMapping("/users/{id}")
public ResponseEntity<User> getUserById(@PathVariable("id") Long id) {
// ...
}

@Schema

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

部分参数：

name：名称
title：标题
description：描述
example：示例值
required：是否为必须
format：属性的格式。如 @Schema(format = “email”)
maxLength 、 minLength：指定字符串属性的最大长度和最小长度
maximum 、 minimum：指定数值属性的最大值和最小值
pattern：指定属性的正则表达式模式
type： 数据类型（integer，long，float，double，string，byte，binary，
boolean，date，dateTime，password），必须是字符串。
如 @Schema=(type=“integer”)
implementation ：具体的实现类，可以是类本身，也可以是父类或实现的接口
代码参考：

@Tag(name = "用户", description = "用户实体类")
@Data
public class User {

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

@Operation

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

部分参数：

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

@Operation(
summary = "操作摘要",
description = "操作的详细描述",
operationId = "operationId",
tags = "tag1",
parameters = {
@Parameter(name = "param1", description = "参数1", required = true),
@Parameter(name = "param2", description = "参数2", required = false)
},
requestBody = @RequestBody(
description = "请求描述",
required = true,
content = @Content(
mediaType = "application/json",
schema = @Schema(implementation = RequestBodyModel.class)
)
),
responses = {
@ApiResponse(responseCode = "200", description = "成功", content = @Content(mediaType = "application/json", schema = @Schema(implementation = ResponseModel.class))),
@ApiResponse(responseCode = "400", description = "错误", content = @Content(mediaType = "application/json", schema = @Schema(implementation = ErrorResponseModel.class)))
}
)
@Tag(name = "标签1")
@ApiResponses(value = {
@ApiResponse(responseCode = "200", description = "成功", content = @Content(mediaType = "application/json", schema = @Schema(implementation = ResponseModel.class))),
@ApiResponse(responseCode = "400", description = "錯誤", content = @Content(mediaType = "application/json", schema = @Schema(implementation = ErrorResponseModel.class)))
})
public void Operation() {
// 逻辑
}

@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”)
代码参考：

@Operation(summary = "根据用户名查询用户列表")
@GetMapping("/query/{username}")
public List<User> queryUserByName(@Parameter(name = "username", in = ParameterIn.PATH, description = "用户名",
required = true) @PathVariable("username") String userName) {
return new ArrayList<>();
}

@Parameters

包含多个 @Parameter 注解，指定多个参数。

代码参考：

@Parameters({
@Parameter(
name = "param1",
description = "description",
required = true,
in = ParameterIn.PATH,
schema = @Schema(type = "string")
),
@Parameter(
name = "param2",
description = "description",
required = true,
in = ParameterIn.QUERY,
schema = @Schema(type = "integer")
)
})

@RequestBody

API 请求的注解

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

@Content

内容注解。

部分参数：

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

场景配置
一. 类及 pojo 上

@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;
}

@Tag

二. Controller 上
@RestController
@RequestMapping(“/user”)
@Tag(name = “用户管理”, description = “用户数据增删改查”)

@Tag(name = "pet", description = "Operations about pets")
@RestController
@RequestMapping("/v1")
public class PetController {

    @Operation(summary = "Find pet by ID", description = "Returns a pet when ID is positive")
    @GetMapping("/pets/{petId}")
    public ResponseEntity<Pet> getPetById(@PathVariable Long petId) {
        // implementation code
    }

    @Operation(summary = "Add a new pet to the store", description = "")
    @PostMapping("/pets")
    public ResponseEntity<Void> addPet(@RequestBody Pet pet) {
        // implementation code
    }
}