1、SpringBoot3整合Knif4j
1、SpringBoot3整合 knif4j
Knife4j官网地址
快速整合
1、添加依赖
<dependency>
<groupId>com.github.xiaoymingroupId>
<artifactId>knife4j-openapi3-jakarta-spring-boot-starterartifactId>
<version>4.3.0version>
dependency>
2、添加配置
knife4j:
enable: true
openapi:
title: Knife4j官方文档
description: "`我是测试`,**你知道吗**
# aaa"
email: [email protected]
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
}
}