SpringBoot3.5.4集成knife4j-openapi3-jakarta-spring-boot-starter

定义目录标题)

SpringBoot3.5.4集成knife4j-openapi3-jakarta-spring-boot-starter

SpringBoot3.5.4集成knife4j-openapi3-jakarta-spring-boot-starter

导包

主要介绍SpringBoot和knife4j-openapi3-jakarta-spring-boot-starter依赖包的导入，

1. 版本选择 ，从官方网站可知，SpringBoot3集成knife4j有版本要求，jdk最低为17版本，knife4j用mave仓库最新版本即可：

2. 配置knife4j：

springdoc-openapi项目配置

springdoc:
swagger-ui:
path: /swagger-ui.html # 原生Swagger UI路径
api-docs:
enabled: true
path: /v3/api-docs # OpenAPI 规范文档路径
group-configs:
- group: ‘default’
paths-to-match: ‘/**’
packages-to-scan: com.ai4j.presentation # 替换为Controller包路径
knife4j:
enable: true # 开启Knife4j增强功能
setting:
language: zh_cn # 中文界面

knife4j的增强配置，不需要增强可以不配

knife4j:
enable: true
setting:
language: zh_cn
3. 使用：
@RestController
@RequestMapping(“body”)
@Tag(name = “body参数”)
public class BodyController {

@Operation(summary = “普通body请求”)
@PostMapping(“/body”)
public ResponseEntity body(@RequestBody FileResp fileResp){
return ResponseEntity.ok(fileResp);
}

@Operation(summary = “普通body请求+Param+Header+Path”)
@Parameters({
@Parameter(name = “id”,description = “文件id”,in = ParameterIn.PATH),
@Parameter(name = “token”,description = “请求token”,required = true,in = ParameterIn.HEADER),
@Parameter(name = “name”,description = “文件名称”,required = true,in=ParameterIn.QUERY)
})
@PostMapping(“/bodyParamHeaderPath/{id}”)
public ResponseEntity bodyParamHeaderPath(@PathVariable(“id”) String id,@RequestHeader(“token”) String token, @RequestParam(“name”)String name,@RequestBody FileResp fileResp){
fileResp.setName(fileResp.getName()+“,receiveName:”+name+“,token:”+token+“,pathID:”+id);
return ResponseEntity.ok(fileResp);
}
}
5. 访问 ：访问Knife4j的文档地址：http://ip:port/doc.html即可查看文档；
6.注解，Spring Boot 3 只支持OpenAPI3规范，常用注解主要有：
一、类级别注解
@Tag

作用：标注在 Controller 类上，定义接口模块分组。

常用参数：

name：模块名称（显示在 UI 左侧分组）

description：模块描述

示例：

java
@Tag(name = “用户管理”, description = “用户注册、登录、信息管理”)
@RestController
@RequestMapping(“/user”)
public class UserController { }
⚙️ 二、方法级别注解
@Operation

作用：标注在接口方法上，描述接口功能。

常用参数：

summary：接口简要说明

description：接口详细描述

示例：

java
@Operation(summary = “创建用户”, description = “需提供完整的用户信息”)
@PostMapping(“/create”)
public Result createUser(@RequestBody User user) { }
@ApiResponses + @ApiResponse

作用：声明接口的 HTTP 响应状态码和说明。

参数：

code：HTTP 状态码（如 200、400）

description：响应描述

示例：

java
@Operation(summary = “更新用户”)
@ApiResponses({
@ApiResponse(responseCode = “200”, description = “更新成功”),
@ApiResponse(responseCode = “404”, description = “用户不存在”)
})
@PutMapping(“/update/{id}”)
public Result updateUser(@PathVariable Long id) { }
📌 三、参数级别注解
@Parameter

作用：描述方法中的单个参数（如 @RequestParam、@PathVariable）。

常用参数：

name：参数名

description：参数说明

required：是否必填

in：参数位置（ParameterIn.QUERY、ParameterIn.PATH 等）

示例：

java
@Operation(summary = “查询用户”)
@GetMapping(“/search”)
public Result searchUser(
@Parameter(name = “keyword”, description = “搜索关键字”, required = true, in = ParameterIn.QUERY)
@RequestParam String keyword) { }
@Parameters

作用：组合多个 @Parameter，用于描述多个参数。

示例：

java
@Operation(summary = “扣减余额”)
@Parameters({
@Parameter(name = “id”, description = “用户ID”, in = ParameterIn.PATH),
@Parameter(name = “amount”, description = “扣减金额”, in = ParameterIn.QUERY)
})
@PostMapping(“/deduct/{id}”)
public Result deductBalance(@PathVariable Long id, @RequestParam BigDecimal amount) { }
文件上传参数

特殊写法：

java
@Operation(summary = “上传头像”)
@PostMapping(“/avatar”)
public Result uploadAvatar(
@Parameter(name = “file”, description = “图片文件”, required = true,
schema = @Schema(type = “string”, format = “binary”))
@RequestPart(“file”) MultipartFile file) { }
📐 四、模型类注解
@Schema

作用：标注在实体类或字段上，描述请求/响应模型。

常用参数：

description：字段说明

example：示例值

required：是否必填（仅用于文档提示）

示例：

java
@Schema(name = “UserVO”, description = “用户响应实体”)
public class UserVO {
@Schema(description = “用户ID”, example = “1001”, required = true)
private Long id;

@Schema(description = "用户名", example = "张三")
private String username;

}
🔄 五、对比：OpenAPI 3 vs Swagger 2 注解
功能 OpenAPI 3 注解 Swagger 2 注解
描述 Controller @Tag @Api
描述接口方法 @Operation @ApiOperation
描述实体类 @Schema（类级别） @ApiModel
描述字段 @Schema（字段级） @ApiModelProperty
描述参数 @Parameter @ApiImplicitParam