Spring Boot 2.x 集成 Knife4j (OpenAPI 3) 完整操作指南

本人在进行Java项目开发时，集成Knife4j 遇到了多方面的问题，在这里进行了一下记录总结。

文章目录

[1. 环境准备](#1. 环境准备)

[1.1 确认 Spring Boot 版本](#1.1 确认 Spring Boot 版本)

[1.2 确认项目结构](#1.2 确认项目结构)

[2. 依赖配置](#2. 依赖配置)

[2.1 添加 Knife4j 依赖](#2.1 添加 Knife4j 依赖)

[2.2 移除旧版本 Swagger 依赖（如有）](#2.2 移除旧版本 Swagger 依赖（如有）)

[3. 配置类设置](#3. 配置类设置)

[3.1 创建 Swagger 配置类](#3.1 创建 Swagger 配置类)

[3.2 可选：WebMvc 配置（解决静态资源问题）](#3.2 可选：WebMvc 配置（解决静态资源问题）)

[4. 应用配置文件](#4. 应用配置文件)

[4.1 application.yml 配置](#4.1 application.yml 配置)

[4.2 application.properties 配置（可选）](#4.2 application.properties 配置（可选）)

[5. 代码注解使用指南](#5. 代码注解使用指南)

[5.1 控制器层注解](#5.1 控制器层注解)

控制器示例：

[5.2 DTO/实体类注解](#5.2 DTO/实体类注解)

[DTO 示例：](#DTO 示例：)

[5.3 响应对象注解](#5.3 响应对象注解)

[6. 安全配置（如果使用 JWT 等安全框架）](#6. 安全配置（如果使用 JWT 等安全框架）)

[7. 访问和测试](#7. 访问和测试)

[7.1 文档访问地址](#7.1 文档访问地址)

[7.2 功能特性](#7.2 功能特性)

[8. 常见问题及解决方案](#8. 常见问题及解决方案)

[8.1 页面无法访问](#8.1 页面无法访问)

[8.2 接口文档不显示](#8.2 接口文档不显示)

[8.3 静态资源加载失败](#8.3 静态资源加载失败)

[9. 版本兼容性参考](#9. 版本兼容性参考)

[10. 最佳实践建议](#10. 最佳实践建议)

1. 环境准备

1.1 确认 Spring Boot 版本

确保使用 Spring Boot 2.x 版本（推荐 2.5.x - 2.7.x）

1.2 确认项目结构

Maven 项目
Spring Boot 2.x
需要 API 文档功能

2. 依赖配置

2.1 添加 Knife4j 依赖

在 pom.xml 中添加：

XML 复制代码

<properties>
    <!-- 推荐使用 4.1.0 或 4.3.0 -->
    <knife4j.version>4.3.0</knife4j.version>
</properties>

<dependencies>
    <!-- Knife4j OpenAPI3 增强依赖 -->
    <dependency>
        <groupId>com.github.xiaoymin</groupId>
        <artifactId>knife4j-openapi3-spring-boot-starter</artifactId>
        <version>${knife4j.version}</version>
    </dependency>
</dependencies>

2.2 移除旧版本 Swagger 依赖（如有）

确保移除以下旧依赖：

XML 复制代码

<!-- 需要移除的依赖 -->
<!--
<dependency>
    <groupId>io.springfox</groupId>
    <artifactId>springfox-swagger2</artifactId>
</dependency>
<dependency>
    <groupId>io.springfox</groupId>
    <artifactId>springfox-swagger-ui</artifactId>
</dependency>
<dependency>
    <groupId>com.github.xiaoymin</groupId>
    <artifactId>knife4j-spring-boot-starter</artifactId>
</dependency>
-->

注意：只保留Knife4j 依赖，其他的swagger相关依赖不要保留，否则会出现冲突！！！

3. 配置类设置

3.1 创建 Swagger 配置类

java 复制代码

package com.example.config;

import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import io.swagger.v3.oas.models.OpenAPI;
import io.swagger.v3.oas.models.info.Info;
import io.swagger.v3.oas.models.info.Contact;
import com.github.xiaoymin.knife4j.spring.annotations.EnableKnife4j;
import lombok.extern.slf4j.Slf4j;

import javax.annotation.PostConstruct;

@Configuration
@EnableKnife4j  // 启用 Knife4j 增强功能
@Slf4j
public class SwaggerConfig {

    @Bean
    public OpenAPI customOpenAPI() {
        log.info("=== 初始化 Knife4j OpenAPI3 配置 ===");
        return new OpenAPI()
                .info(apiInfo());
    }

    private Info apiInfo() {
        return new Info()
                .title("项目名称 API 文档")
                .description("项目描述信息")
                .termsOfService("http://localhost:8080/")
                .contact(new Contact()
                        .name("开发团队")
                        .url("http://localhost:8080/")
                        .email("developer@example.com"))
                .version("1.0");
    }

    @PostConstruct
    public void init() {
        log.info("=== Knife4j OpenAPI3 配置初始化完成 ===");
        log.info("文档地址: http://localhost:8080/doc.html");
        log.info("OpenAPI JSON: http://localhost:8080/v3/api-docs");
    }
}

3.2 可选：WebMvc 配置（解决静态资源问题）

java 复制代码

package com.example.config;

import org.springframework.context.annotation.Configuration;
import org.springframework.web.servlet.config.annotation.ResourceHandlerRegistry;
import org.springframework.web.servlet.config.annotation.WebMvcConfigurer;

@Configuration
public class WebMvcConfig implements WebMvcConfigurer {
    
    @Override
    public void addResourceHandlers(ResourceHandlerRegistry registry) {
        // 确保 Knife4j 的静态资源能够正常访问
        registry.addResourceHandler("doc.html")
                .addResourceLocations("classpath:/META-INF/resources/");
        registry.addResourceHandler("/webjars/**")
                .addResourceLocations("classpath:/META-INF/resources/webjars/");
    }
}

若访问文档地址: http://localhost:8080/doc.html遇到Knife4j文档请求异常的错误提示（如下图），可以添加WebMvc 配置来进行解决，我出现这个错误就是添加WebMvc 配置解决的

4. 应用配置文件

4.1 application.yml 配置

java 复制代码

# Spring 配置
spring:
  mvc:
    pathmatch:
      matching-strategy: ant_path_matcher  # Spring Boot 2.6+ 必须配置

# Knife4j 配置
knife4j:
  enable: true
  setting:
    language: zh-CN  # 中文界面

4.2 application.properties 配置（可选）

java 复制代码

# Spring 配置
spring.mvc.pathmatch.matching-strategy=ant_path_matcher

# Knife4j 配置
knife4j.enable=true
knife4j.setting.language=zh-CN

5. 代码注解使用指南

5.1 控制器层注解

新版 OpenAPI3 注解

	OpenAPI3 注解	说明
	`@Tag`	控制器分类
	`@Operation`	接口操作
	`@Parameter`	参数说明
	`@ApiResponse`	响应说明

控制器示例：

java 复制代码

@RestController
@RequestMapping("/api/user")
@Tag(name = "用户管理", description = "用户注册、登录、信息管理等接口")
public class UserController {

    @PostMapping("/login")
    @Operation(summary = "用户登录", description = "通过用户名和密码登录系统")
    public Result<LoginVO> login(
            @Parameter(description = "登录参数", required = true)
            @Valid @RequestBody LoginDTO loginDTO) {
        // 业务逻辑
    }
}

5.2 DTO/实体类注解

新版 OpenAPI3 注解

	OpenAPI3 注解	说明
	`@Schema`	模型说明
	`@Schema`	属性说明

DTO 示例：

java 复制代码

@Data
@Schema(description = "用户登录请求参数")
public class LoginDTO {
    
    @Schema(description = "用户名", example = "admin", required = true)
    @NotBlank(message = "用户名不能为空")
    private String username;
    
    @Schema(description = "密码", example = "123456", required = true)
    @NotBlank(message = "密码不能为空")
    private String password;
}

5.3 响应对象注解

java 复制代码

@Data
@Schema(description = "通用返回结果")
public class Result<T> {
    @Schema(description = "状态码", example = "200")
    private Integer code;
    
    @Schema(description = "提示信息", example = "成功")
    private String msg;
    
    @Schema(description = "返回数据")
    private T data;
}

6. 安全配置（如果使用 JWT 等安全框架）

在安全过滤器中放行 Knife4j 相关路径：

java 复制代码

// 在 JWT 过滤器或安全配置中
private boolean isPublicUri(String uri) {
    return uri.startsWith("/doc.html") ||
           uri.startsWith("/webjars/") ||
           uri.startsWith("/v3/api-docs") ||
           uri.startsWith("/favicon.ico") ||
           uri.equals("/") ||
           uri.startsWith("/swagger-resources");
}

7. 访问和测试

7.1 文档访问地址

Knife4j 增强文档 : http://localhost:8080/doc.html
OpenAPI JSON : http://localhost:8080/v3/api-docs

7.2 功能特性

接口分组管理
在线调试
接口搜索
离线文档导出
全局参数设置
接口权限控制

8. 常见问题及解决方案

8.1 页面无法访问

检查依赖版本：确认 Knife4j 版本兼容性
检查配置 ：确认 @EnableKnife4j 注解已添加
清除缓存：浏览器 Ctrl+F5 强制刷新

8.2 接口文档不显示

检查注解：确认使用了正确的 OpenAPI3 注解
检查包扫描：确认控制器在 Spring 扫描路径内
检查安全配置：确认 Knife4j 路径已放行

8.3 静态资源加载失败

添加 WebMvc 配置：配置静态资源处理器
检查路径匹配策略 ：确认 ant_path_matcher 配置

9. 版本兼容性参考

Spring Boot 版本	推荐 Knife4j 版本	说明
2.5.x	4.1.0 - 4.3.0	稳定兼容
2.6.x	4.1.0 - 4.3.0	需配置 pathmatch
2.7.x	4.3.0	最新稳定

10. 最佳实践建议

统一响应格式：所有接口使用统一的 Result 包装类
详细接口描述：为每个接口和参数添加清晰的描述
分组管理：按模块对接口进行分组
版本控制：在 API 路径中包含版本号
权限控制：在文档中明确接口的访问权限要求