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的版本必须相互兼容：

<!-- 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 的关键参数：

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 的配置类，用于定义接口文档的基本信息和分组规则。以下是一个典型示例：

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 的静态资源路径：

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 项目中稳定运行。