当前位置：首页 > news >正文

若依框架 (Spring Boot 3) 集成 knife4j 实现 OpenAPI 文档增强

news 2025/9/24 10:26:27

由于官方集成 knife4j 实现 OpenAPI 文档增强的文档说明比较模糊精简，CSDN优质内容又需要付费，本文提供免费配置的一套方法。

若依框架(Spring Boot 3版本)通过集成knife4j可以实现更强大的API文档功能，本文将详细介绍完整的集成步骤和最佳实践。

一、什么是knife4j？

knife4j是基于OpenAPI 3.0规范的API文档生成工具，是Swagger的增强实现，提供了更友好的UI界面和更丰富的功能，特别适合国内开发者使用。它支持接口调试、文档导出、全局参数配置等实用功能。

二、集成步骤

1. 添加依赖

在ruoyi-admin模块的pom.xml中添加knife4j依赖：

<!-- ruoyi-springboot3 / springdoc knife4j 配置 -->
<dependency><groupId>com.github.xiaoymin</groupId><artifactId>knife4j-openapi3-jakarta-spring-boot-starter</artifactId><version>4.4.0</version>
</dependency>

该依赖已包含OpenAPI 3.0的核心功能，无需额外引入springdoc基础包。

2. 配置安全框架

修改安全配置类，允许访问knife4j的静态资源和文档页面，在\ruoyi-framework\src\main\java\com\mc\framework\config\SecurityConfig.java的安全规则中添加：

.requestMatchers("/webjars/**", "/doc.html", "/v3/api-docs/**", "/swagger-resources/**").permitAll()

这确保了在启用Spring Security的情况下，仍然可以正常访问API文档。

3. 配置knife4j

在application.yml中添加knife4j的配置：

# knife4j 配置
knife4j:enable: true           # 是否启用 knife4j 页面production: false      # 生产模式设置，true会关闭调试功能basic:enable: false        # 是否启用基础认证(可选)username: ruoyi      # 基础认证用户名password: 123456     # 基础认证密码setting:swagger-model-name: 心理健康系统实体类  # 模型名称language: zh-CN      # 界面语言设置为中文

4. 配置SpringDoc

在application.yml中添加SpringDoc配置，定制API文档生成规则：

# Springdoc配置
springdoc:api-docs:path: /v3/api-docs   # API文档JSON数据访问路径swagger-ui:enabled: true        # 是否启用Swagger UIpath: /swagger-ui.html  # Swagger UI访问路径tags-sorter: alpha   # 标签排序方式group-configs:- group: 'default'   # 接口分组名称display-name: '测试模块'  # 分组显示名称paths-to-match: '/**'    # 匹配的接口路径packages-to-scan: com.mc.web.controller.tool  # 需要扫描的控制器包路径

5. 在业务模块中使用

在业务模块的pom.xml中添加Swagger注解依赖：

<dependency><groupId>io.swagger.core.v3</groupId><artifactId>swagger-annotations-jakarta</artifactId><version>2.2.30</version>
</dependency>

三、注解使用详解

OpenAPI 3.0规范使用了全新的注解体系，与之前的Swagger 2.x有较大区别，下面是主要注解的使用示例：

1. 控制器注解示例

import io.swagger.v3.oas.annotations.Operation;
import io.swagger.v3.oas.annotations.Parameter;
import io.swagger.v3.oas.annotations.Parameters;
import io.swagger.v3.oas.annotations.enums.ParameterIn;
import io.swagger.v3.oas.annotations.responses.ApiResponse;
import io.swagger.v3.oas.annotations.responses.ApiResponses;
import io.swagger.v3.oas.annotations.tags.Tag;@RestController
@RequestMapping("/tool/demo")
@Tag(name = "测试接口", description = "测试接口相关操作")
public class DemoController {@Operation(summary = "获取列表", description = "获取测试数据列表")@GetMapping("/list")public TableDataInfo list(Demo demo) {startPage();List<Demo> list = demoService.selectDemoList(demo);return getDataTable(list);}@Operation(summary = "获取详情", description = "根据ID获取测试数据详情")@ApiResponses(value = {@ApiResponse(responseCode = "200", description = "查询成功"),@ApiResponse(responseCode = "404", description = "数据不存在")})@GetMapping(value = "/{id}")public AjaxResult getInfo(@Parameter(name = "id", description = "数据ID", required = true, in = ParameterIn.PATH)@PathVariable("id") Long id) {return success(demoService.selectDemoById(id));}@Operation(summary = "新增数据", description = "新增测试数据")@PostMappingpublic AjaxResult add(@Parameter(description = "测试数据信息", required = true)@Validated @RequestBody Demo demo) {return toAjax(demoService.insertDemo(demo));}
}

2. 实体类注解示例

import io.swagger.v3.oas.annotations.media.Schema;
import jakarta.validation.constraints.Max;
import jakarta.validation.constraints.Min;
import jakarta.validation.constraints.NotBlank;@Data
@Schema(description = "测试实体类")
public class Demo {private static final long serialVersionUID = 1L;@Schema(value = "主键ID", example = "1")private Long id;@Schema(value = "名称", required = true, example = "测试名称")@NotBlank(message = "名称不能为空")private String name;@Schema(value = "年龄", example = "20", minimum = "0", maximum = "150")@Min(value = 0, message = "年龄不能小于0")@Max(value = 150, message = "年龄不能大于150")private Integer age;@Schema(value = "创建时间")private Date createTime;
}

四、注解版本说明

Swagger 2.x 注解	OpenAPI 3.x 注解	说明
@Api	@Tag	描述控制器
@ApiOperation	@Operation	描述接口方法
@ApiParam	@Parameter	描述参数
@ApiModel	@Schema	描述实体类
@ApiModelProperty	@Schema	描述实体类字段
@ApiResponses	@ApiResponses	描述接口响应