Knife4j 4.5.0 与 Spring Boot 3.x 版本兼容问题解决方案

解决兼容问题

调试发现问题

1. 依赖兼容问题

最终调试测试发现，Knife4j 4.5.0 使用的依赖 springdoc-openapi-starter-webmvc-ui 2.3.0 和 Spring Boot 3.x.x 版本不匹配。测试发现 springdoc-openapi-starter-webmvc-ui 2.8.9 适配。

2. Knife4j 配置问题

配置文件中添加 knife4j: enable: true 会导致错误。截至当前版本，不要加这个 enable: true 配置选项，或直接设置为 enable: false。

Maven 依赖覆盖

注意：多模块项目需版本管理覆盖，单模块自行决策。

父 pom.xml

<properties> <!-- knife4j swagger 文档版本 --> <knife4j.version>4.5.0</knife4j.version> <!-- swagger ui 文档版本 --> <springdoc-openapi.version>2.8.9</springdoc-openapi.version> </properties>
<dependencyManagement>
  <dependencies>
    <!-- knife4j swagger -->
    <dependency>
      <groupId>com.github.xiaoymin</groupId>
      <artifactId>knife4j-openapi3-jakarta-spring-boot-starter</artifactId>
      <version>${knife4j.version}</version>
    </dependency>
    <!-- springdoc (覆盖 knife4j 版本) -->
    <dependency>
      <groupId>org.springdoc</groupId>
      <artifactId>springdoc-openapi-starter-webmvc-ui</artifactId>
      <version>${springdoc-openapi.version}</version>
    </dependency>
  </dependencies>
</dependencyManagement>

yml 配置文件

enable 先显示设置 false，未来如果版本变化需要显示时就设置 true 即可。

knife4j:
  enable: false
  setting:
    language: zh_cn

刷新 Maven 依赖

验证结果： com.github.xiaoymin:knife4j-openapi3-jakarta-spring-boot-starter:4.5.0 ----> org.springdoc:springdoc-openapi-starter-webmvc-ui:2.8.9

启动项目验证

Knife4j、Swagger UI、api-docs 均可正常访问。