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

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

参考

Knife4j · 集 Swagger2 及 OpenAPI3 为一体的增强解决方案

兼容版本说明

Knife4j 4.5.0

• 底层依赖 Swagger 兼容版本：springdoc-openapi-starter-webmvc-ui 2.3.0

Spring Boot 3.x.x +

• 只支持 OpenAPI3 规范

报错内容

Knife4j 异常

访问 http://localhost:8080/doc.html#/home 解析不到内容。

Swagger UI 异常

访问 http://localhost:8080/swagger-ui/index.html 报错提示：Unable to render this definition The provided definition does not specify a valid version field.

JSON 外部工具 api-docs 异常

访问 localhost:8080/v3/api-docs 返回通用统一返回 DTO 格式异常。

{"code": 500, "msg": "Handler dispatch failed: java.lang.NoSuchMethodError: 'java.util.List org.springdoc.core.properties.SpringDocConfigProperties.getGroupConfigs()'", "data": null}

后端控制台异常内容

jakarta.servlet.ServletException: Handler dispatch failed: java.lang.NoSuchMethodError: 'java.util.List org.springdoc.core.properties.SpringDocConfigProperties.getGroupConfigs()' at org.springframework.web.servlet.DispatcherServlet.doDispatch(DispatcherServlet.java:1104) ~[spring-webmvc-6.2.8.jar:6.2.8] ...
Caused by: java.lang.NoSuchMethodError: 'java.util.List org.springdoc.core.properties.SpringDocConfigProperties.getGroupConfigs()' at com.github.xiaoymin.knife4j.spring.extension.Knife4jOpenApiCustomizer.addOrderExtension(Knife4jOpenApiCustomizer.java:75) ~[knife4j-openapi3-jakarta-spring-boot-starter-4.5.0.jar:na]

解决兼容问题

调试发现问题

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 均可正常访问。