SpringBoot3整合Knife4j

文章目录

- 1. 引入依赖
- 2. yml配置文件
- 3. 常用注解
- - 3.1 类级别注解
  - 3.2 方法级别注解
  - 3.3 参数级别注解
  - 3.4 模型类注解
- 4. 访问界面

1. 引入依赖

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

2. yml配置文件

# 配置springdoc-openapi，用于文档化和访问API
springdoc:# 配置Swagger UI的访问路径和排序方式swagger-ui:path: /swagger-ui.html  # Swagger UI的访问路径tags-sorter: alpha      # 按字母顺序排序标签operations-sorter: alpha  # 按字母顺序排序操作# 配置API文档的访问路径api-docs:path: /v3/api-docs  # API文档的访问路径# 配置API分组，用于组织和管理APIgroup-configs:- group: 'default'   # API分组名称paths-to-match: '/**'  # 匹配所有路径packages-to-scan: com.feng.mybatisplusdemo1.contraller  # 扫描的包，用于自动发现API# knife4j的增强配置，不需要增强可以不配
knife4j:enable: truesetting:language: zh_cn

3. 常用注解

3.1 类级别注解

@Tag

用于为API操作分组。

@Tag(name = "测试类",description = "测试swagger")
@RestController
@RequestMapping("/test")
public class TestController {}

属性：

name：标签名。
description：标签描述。

3.2 方法级别注解

@Operation

用于描述控制器类中的单个操作。

    @Operation(summary = "测试方法",description = "测试swagger方法的描述")@PostMapping("/{id}")public void test(@Parameter(description = "id",required = true) @PathVariable("id") Long id){System.out.println("test================"+id);}

属性：

summary：简短描述。
description：详细说明。
tags：标签，用于分类API。
responses：响应描述。

@ApiResponses

用于描述API操作的响应。

@Tag(name = "测试类",description = "测试swagger")
@ApiResponses(value = {@ApiResponse(responseCode = "200", description = "成功", content = @Content(mediaType = "application/json", schema = @Schema(implementation = User.class))),@ApiResponse(responseCode = "400", description = "请求参数错误"),@ApiResponse(responseCode = "404", description = "找不到资源"),@ApiResponse(responseCode = "500", description = "服务器内部错误")
})
@RestController
@RequestMapping("/test")
public class TestController {@Operation(summary = "测试方法",description = "测试swagger方法的描述")@PostMapping("/{id}")public void test(@Parameter(description = "id",required = true) @PathVariable("id") Long id){System.out.println("test================"+id);}}

属性：

value：包含多个@ApiResponse注解。

@ApiResponse

用于描述单个响应。。

属性：

responseCode：HTTP状态码。
description：描述信息。
content：响应内容类型和模式。

3.3 参数级别注解

@Parameter

用于描述单个参数

    @Operation(summary = "测试方法",description = "测试swagger方法的描述")@PostMapping("/{id}")public void test(@Parameter(description = "id",required = true) @PathVariable("id") Long id){System.out.println("test================"+id);}

属性：

name：参数名。
description：参数描述。
required：是否必须参数。
schema：参数模式。

@Parameters

用于描述多个参数

    @PutMapping("{id}/dedeuction/{balance}")@Operation(summary = "余额修改接口",description = "通过ID扣减相应金额")@Parameters({@Parameter(name = "id",description = "用户ID" ),@Parameter(name = "balance",description = "修改金额")})public void updateBalanceById(@PathVariable("id") Long id,@PathVariable("balance") Integer balance){System.out.println("修改ID:"+id+"用户金额，扣减："+balance);}

属性：

value：包含多个@Parameter注解。

3.4 模型类注解

@Schema

用于描述模型类和字段的信息

@Data
@Schema(description = "用户VO实体")
public class UserVO {@Schema(description = "用户id")private Long id;@Schema(description = "用户名")private String username;@Schema(description = "详细信息")private String info;@Schema(description = "使用状态（1正常 2冻结）")private Integer status;@Schema(description = "账户余额")private Integer balance;
}