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