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

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

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

一、什么是knife4j？

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

二、集成步骤

1. 添加依赖

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

xml 复制代码

<!-- 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的安全规则中添加：

java 复制代码

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

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

3. 配置knife4j

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

yaml 复制代码

# 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文档生成规则：

yaml 复制代码

# Springdoc配置
springdoc:
  api-docs:
    path: /v3/api-docs   # API文档JSON数据访问路径
  swagger-ui:
    enabled: true        # 是否启用Swagger UI
    path: /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注解依赖：

xml 复制代码

<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. 控制器注解示例

java 复制代码

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 = "新增测试数据")
    @PostMapping
    public AjaxResult add(
        @Parameter(description = "测试数据信息", required = true)
        @Validated @RequestBody Demo demo) {
        return toAjax(demoService.insertDemo(demo));
    }
}

2. 实体类注解示例

java 复制代码

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	描述接口响应

在Spring Boot 3项目中，推荐使用OpenAPI 3.x注解，因为：

更好地支持Jakarta EE规范
功能更丰富，配置更灵活
与knife4j-openapi3-jakarta依赖更匹配

五、访问文档

启动项目后，可以通过以下地址访问API文档：

Knife4j增强UI：http://localhost:8080/doc.html
原生Swagger UI：http://localhost:8080/swagger-ui.html
API数据JSON：http://localhost:8080/v3/api-docs

六、knife4j增强功能

集成knife4j后，相比原生Swagger可以获得以下增强功能：

更美观的中文界面，符合国内使用习惯
支持接口调试历史记录
文档导出功能（支持Markdown、HTML、Word等格式）
全局参数配置（如Token等公共参数）
接口排序与分组管理
离线文档功能
接口权限控制

总结

通过本文的步骤，若依框架(Spring Boot 3版本)中快速集成knife4j，获得强大的API文档功能。合理使用OpenAPI 3.x注解可以使文档更加清晰、专业，显著提升前后端协作效率。