Knife4j 4.5.0 + Spring Boot 3.4.11 版本兼容问题解决方案

引言

在 Spring Boot 3.4.11 项目中集成 Knife4j 4.5.0 时，很多开发者会遇到接口文档无法正常显示、页面白屏、API 分组失败等问题。本文将深入分析版本兼容性痛点，并提供可直接落地的解决方案。

问题现象

当你满怀期待地在 Spring Boot 3.4.11 项目中引入 Knife4j 4.5.0 时，可能会遇到以下几种典型问题：

接口文档页面白屏：访问 /doc.html 时页面一片空白，浏览器控制台报 404 或 JS 资源加载失败。
分组接口不显示：虽然在代码中正确配置了分组，但页面上看不到对应的 API 列表。
Swagger 资源请求 404：访问 /v3/api-docs 时返回 404，导致文档无法生成。
启动阶段报错：项目启动时控制台输出 "Failed to start bean 'documentationPluginsBootstrapper'" 等错误信息。

原因分析

这些问题的本质是 Knife4j 4.5.0 与 Spring Boot 3.4.11 的版本兼容性冲突。具体原因包括：

Swagger 核心版本不匹配：Spring Boot 3.x 需要依赖 springdoc-openapi 2.x 版本，而 Knife4j 4.x 正是基于 springdoc-openapi 构建的。如果 springdoc 版本与 Knife4j 不匹配，会导致资源映射失败。
Spring MVC 路径匹配策略变更：Spring Boot 3.x 默认采用 PathPatternParser 作为路径匹配策略，而 springdoc-openapi 内置的 swagger-ui 资源路径可能无法正确映射，导致静态资源 404。
自动配置类加载顺序问题：Spring Boot 3.x 的自动配置机制发生了微妙变化，可能导致 Knife4j 的自动配置在 Swagger 自动配置之前加载，引发 Bean 创建失败。
Servlet 容器兼容性问题：如果你的项目使用 Undertow 而非 Tomcat 作为嵌入式容器，也可能遇到资源路径映射的额外问题。

完整解决方案

下面提供一套经过验证的完整配置方案，能够有效解决 Knife4j 4.5.0 与 Spring Boot 3.4.11 的兼容性问题。

1. Maven 依赖配置

首先确保 POM 文件中引入正确版本的依赖。核心是 springdoc-openapi-starter-webmvc-ui 和 knife4j-openapi3-jakarta-spring-boot-starter 的版本必须相互兼容：

xml 复制代码

<!-- SpringDoc OpenAPI 核心依赖 -->
<dependency>
    <groupId>org.springdoc</groupId>
    <artifactId>springdoc-openapi-starter-webmvc-ui</artifactId>
    <version>2.6.0</version>
</dependency>
<!-- Knife4j 增强 UI -->
<dependency>
<groupId>com.github.xiaoymin</groupId>
<artifactId>knife4j-openapi3-jakarta-spring-boot-starter</artifactId>
<version>4.5.0</version>
</dependency>

2. 配置文件（application.yml）

在配置文件中需要明确指定 SpringDoc 和 Knife4j 的关键参数：

yaml 复制代码

springdoc:
  swagger-ui:
    path: /swagger-ui.html
    tags-sorter: alpha
    operations-sorter: alpha
  api-docs:
    path: /v3/api-docs
  group-configs:
    - group: 'default'
      paths-to-match: '/**'
      packages-to-scan: com.example.controller
Knife4j 专属配置
knife4j:
enable: true
setting:
language: zh_cn
swagger-model-name: 实体类列表
enable-footer: false
enable-footer-custom: true
footer-custom-content: 版权所有 | Powered by Knife4j
关键：确保路径匹配策略兼容
spring:
mvc:
pathmatch:
matching-strategy: ant_path_matcher</user_query>

3. Java 配置类

除了配置文件，还需要在项目中编写一个 Swagger 或 Knife4j 的配置类，用于定义接口文档的基本信息和分组规则。以下是一个典型示例：

java 复制代码

import io.swagger.v3.oas.models.OpenAPI;
import io.swagger.v3.oas.models.info.Info;
import io.swagger.v3.oas.models.info.Contact;
import org.springdoc.core.models.GroupedOpenApi;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
@Configuration
public class SwaggerConfig {
@Bean
public OpenAPI customOpenAPI() {
    return new OpenAPI()
            .info(new Info()
                    .title("项目接口文档")
                    .version("1.0.0")
                    .description("基于 Spring Boot 3.4.11 和 Knife4j 4.5.0 的 API 文档")
                    .contact(new Contact()
                            .name("开发团队")
                            .email("dev@example.com")));
}
@Bean
public GroupedOpenApi publicApi() {
return GroupedOpenApi.builder()
.group("default")
.pathsToMatch("/**")
.packagesToScan("com.example.controller")
.build();
}
}

注意：GroupedOpenApi 和 OpenAPI 都来自 org.springdoc.core 包，与 Spring Boot 3.x 完全兼容。

4. 静态资源映射与路径匹配策略

如果在配置文件中设置了 spring.mvc.pathmatch.matching-strategy=ant_path_matcher 仍无法解决静态资源 404，可以通过实现 WebMvcConfigurer 来手动映射 Swagger 和 Knife4j 的静态资源路径：

java 复制代码

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) {
    registry.addResourceHandler("/doc.html")
            .addResourceLocations("classpath:/META-INF/resources/");
    registry.addResourceHandler("/webjars/**")
            .addResourceLocations("classpath:/META-INF/resources/webjars/");
}
}

同时确保你的 Spring Boot 应用没有通过 spring.web.resources.static-locations 覆盖默认路径。如果使用了 Spring Security ，还需要放行 /doc.html、/swagger-ui/**、/v3/api-docs/** 和 /webjars/** 等路径。

5. 验证与排查步骤

完成上述配置后，重新启动项目并按照以下步骤验证：

检查启动日志：查看控制台是否输出 Swagger 映射信息和 Knife4j 的 banner，确认自动配置已加载。
访问 API 文档 JSON ：在浏览器或 Postman 中访问 http://localhost:8080/v3/api-docs，若能返回正确的 JSON 数据结构，则说明 Swagger 核心配置成功。
访问 Knife4j 页面 ：打开 http://localhost:8080/doc.html，页面应能正常显示接口列表，支持调试和参数填写。
排查常见错误 ：
- 若 JSON 有数据但页面白屏，请检查浏览器控制台是否有 JS 资源 404，确认静态资源映射正确。
- 若分组不显示，请检查 GroupedOpenApi 的 packagesToScan 路径是否与实际 Controller 包路径一致，并检查分组名称是否匹配。
- 若启动报 documentationPluginsBootstrapper 错误，请确认 springdoc 版本为 2.6.0 且未重复引入旧版 Swagger 依赖。

总结

Knife4j 4.5.0 与 Spring Boot 3.4.11 的兼容问题大部分源自 SpringDoc 版本匹配和路径映射策略。通过本文提供的 Maven 依赖、YAML 配置、Java 配置类、静态资源映射和验证步骤，你可以快速解决接口文档白屏、分组不显示等问题，让 Knife4j 在 Spring Boot 3.4.11 项目中稳定运行。