引言
使用 JDK 21 版本创建的 Spring Boot 项目，在 SpringBoot3 整合 Swagger3 过程中遇到一些问题。网上很多关于 SpringBoot3 整合 Knife4j(Swagger3) 的步骤完全照着做会有很多兼容性问题。现将遇到的问题及解决方案记录如下。
SpringBoot3 整合 Knife4j(Swagger3) 关键点梳理
1. 添加/修改依赖
Spring Boot 3.x 必须使用 knife4j-openapi3-jakarta（Jakarta 命名空间）。
<dependency>
<groupId>com.github.xiaoymin</groupId>
<artifactId>knife4j-openapi3-jakarta-spring-boot-starter</artifactId>
<version>4.5.0</version>
</dependency>
注意：不要使用旧版本的 knife4j-spring-boot-starter，否则会出现兼容性问题。
SpringBoot3.x 相比 SpringBoot2.x 特性上有很大改变，必须选择 SpringBoot3.x 版本兼容的 Knife4j 版本。
2. 添加配置文件
创建配置类以自定义 OpenAPI 信息、分组及全局响应码。
package com.Knife4j;
import cn.hutool.core.util.RandomUtil;
import io.swagger.v3.oas.models.OpenAPI;
import io.swagger.v3.oas.models.Operation;
import io.swagger.v3.oas.models.PathItem;
import io.swagger.v3.oas.models.Paths;
import io.swagger.v3.oas.models.info.Contact;
import io.swagger.v3.oas.models.info.Info;
import io.swagger.v3.oas.models.info.License;
import io.swagger.v3.oas.models.media.Content;
import io.swagger.v3.oas.models.media.MediaType;
import io.swagger.v3.oas.models.media.Schema;
import io.swagger.v3.oas.models.responses.ApiResponse;
import io.swagger.v3.oas.models.responses.ApiResponses;
import org.slf4j.Logger;
import org.slf4j.LoggerFactory;
import org.springdoc.core.customizers.GlobalOpenApiCustomizer;
import org.springdoc.core.models.GroupedOpenApi;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import java.util.Map;
import java.util.HashMap;
@Configuration
public class Knife4jConfig {
private final static Logger logger = LoggerFactory.getLogger(Knife4jConfig.class);
private static final String SERVICE_URL = "http://localhost:8886/doc.html";
private static final ;
;
;
;
;
;
GroupedOpenApi {
GroupedOpenApi.builder()
.group()
.displayName()
.packagesToScan()
.addOpenApiCustomizer(::setCustomStatusCode)
.build();
}
GroupedOpenApi {
GroupedOpenApi.builder()
.group()
.displayName()
.packagesToScan()
.addOpenApiCustomizer(::setCustomStatusCode)
.build();
}
GroupedOpenApi {
GroupedOpenApi.builder()
.group()
.displayName()
.packagesToScan()
.addOpenApiMethodFilter(method -> method.isAnnotationPresent(io.swagger.v3.oas.annotations.Operation.class))
.addOpenApiCustomizer(::setCustomStatusCode)
.build();
}
OpenAPI {
()
.info( ()
.title(API_INFO_TITLE)
.description(API_INFO_DESCRIPTION)
.version(API_INFO_VERSION)
.contact( ().name(API_INFO_NAME).email(API_INFO_EMAIL))
.license( ().name(API_INFO_LICENSE).url(SERVICE_URL)));
}
{
(openApi.getPaths() != ) {
openApi.getPaths();
(Map.Entry<String, PathItem> entry : paths.entrySet()) {
entry.getKey();
entry.getValue();
value.getPut();
value.getGet();
value.getDelete();
value.getPost();
(put != ) {
put.setResponses(handleResponses(put.getResponses()));
}
(get != ) {
get.setResponses(handleResponses(get.getResponses()));
}
(delete != ) {
delete.setResponses(handleResponses(delete.getResponses()));
}
(post != ) {
post.setResponses(handleResponses(post.getResponses()));
}
}
}
}
ApiResponses {
();
(Map.Entry<String, ApiResponse> entry : responses.entrySet()) {
entry.getKey();
entry.getValue();
(apiResponse != ) {
content = apiResponse.getContent();
;
}
}
Map<Integer, String> map = StatusCode.toMap();
(Map.Entry<Integer, String> entry : map.entrySet()) {
();
api.setContent(content);
api.description(entry.getValue());
responses.addApiResponse(entry.getKey() + , api);
}
responses;
}
GlobalOpenApiCustomizer {
openApi -> {
(openApi.getTags() != ) {
openApi.getTags().forEach(tag -> {
Map<String, Object> map = <>();
map.put(, RandomUtil.randomInt(, ));
tag.setExtensions(map);
});
}
(openApi.getPaths() != ) {
openApi.addExtension(, );
openApi.getPaths().addExtension(, RandomUtil.randomInt(, ));
}
};
}
OpenAPI {
()
.info( ()
.title()
.version()
.description()
.termsOfService()
.license( ().name()
.url()));
}
}
3. 启动 SpringBoot
启动成功，访问：http://localhost:8886/doc.html
页面效果如图：
4. 配置项
springdoc:
# 防止全局异常处理器的响应定义覆盖所有接口
override-with-generic-response: false
# 禁用损坏引用清理（如遇到 Schema 解析问题可尝试）
remove-broken-reference-definitions: false
swagger-ui:
path: /doc.html
tags-sorter: alpha
operations-sorter: alpha
api-docs:
path: /v3/api-docs
group-configs:
- group: 'default'
paths-to-match: '/**'
packages-to-scan: com
knife4j:
enable: true
setting:
language: zh_cn
运行结果（目前访问 doc.html，会自动跳转到 swagger-ui/index.html）：
5. 配置项中添加更多控制细节
# 配置 Knife4j，以启用 Swagger 文档的增强功能和定制化展示
knife4j:
# 启用 Knife4j 扩展
enable: true
# 配置展示的文档分组
documents:
- group: 2.X 版本
name: 接口签名
locations: classpath:sign/*
# 配置 Knife4j 的展示细节和功能开关
setting:
# 设置界面语言
language: zh-CN
# 启用 Swagger 模型展示
enable-swagger-models: true
# 启用文档管理功能
enable-document-manage: true
# 设置 Swagger 模型的显示名称
swagger-model-name: 实体类列表
# 是否显示版本信息
enable-version: false
# 是否启用参数缓存刷新
enable-reload-cache-parameter: false
# 启用后端脚本支持
enable-after-script: true
# 过滤特定方法类型的 multipart/form-data 接口
enable-filter-multipart-api-method-type: POST
# 是否过滤所有 multipart/form-data 类型的接口
enable-filter-multipart-apis: false
# 启用请求缓存
enable-request-cache: true
# 是否启用搜索功能
enable-search: false
目前启动时会报如下错误（暂时未解决）：
2025-12-24T23:04:56.337+08:00 WARN 35067 --- [langchain4jAI] [ restartedMain] ConfigServletWebServerApplicationContext : Exception encountered during context initialization - cancelling refresh attempt: org.springframework.beans.factory.UnsatisfiedDependencyException: Error creating bean with name 'knife4jAutoConfiguration' defined in URL [jar:file:/Users/apple/.m2/repository/com/github/xiaoymin/knife4j-openapi3-jakarta-spring-boot-starter/4.5.0/knife4j-openapi3-jakarta-spring-boot-starter-4.5.0.jar!/com/github/xiaoymin/knife4j/spring/configuration/Knife4jAutoConfiguration.class]: Unsatisfied dependency expressed through constructor parameter 0: No qualifying bean of type 'com.github.xiaoymin.knife4j.spring.configuration.Knife4jProperties' available: expected single matching bean but found 2: knife4jProperties,knife4j-com.github.xiaoymin.knife4j.spring.configuration.Knife4jProperties
2025-12-24T23:04:56.444+08:00 INFO 35067 --- [langchain4jAI] [ restartedMain] o.apache.catalina.core.StandardService : Stopping service [Tomcat]
Error starting ApplicationContext. To display the condition evaluation report re-run your application with 'debug' enabled.
APPLICATION FAILED TO START
Description:
Parameter 0 of constructor in com.github.xiaoymin.knife4j.spring.configuration.Knife4jAutoConfiguration required a single bean, but 2 were found:
- knife4jProperties: defined in URL [jar:file:/Users/apple/.m2/repository/com/github/xiaoymin/knife4j-openapi3-jakarta-spring-boot-starter/4.5.0/knife4j-openapi3-jakarta-spring-boot-starter-4.5.0.jar!/com/github/xiaoymin/knife4j/spring/configuration/Knife4jProperties.class]
- knife4j-com.github.xiaoymin.knife4j.spring.configuration.Knife4jProperties: defined in unknown location
This may be due to missing parameter name information
Action:
Consider marking one of the beans as @Primary, updating the consumer to accept multiple beans, or using @Qualifier to identify the bean that should be consumed
Ensure that your compiler is configured to use the '-parameters' flag.
You may need to update both your build tool settings as well as your IDE.
问题梳理
问题 1：启动 SpringBoot 后访问 doc.html 页面报错
java.lang.NoSuchMethodError: 'void org.springframework.web.method.ControllerAdviceBean.<init>(java.lang.Object)' at org.springdoc.core.service.GenericResponseService.lambda$getGenericMapResponse$8(GenericResponseService.java:702) ~[springdoc-openapi-starter-common-2.3.0.jar:2.3.0]
网上查了很多资料，最终看到下面的两个内容解决了问题：
由于不想降低 SpringBoot 的版本，故而选择修改配置文件。最终解决办法是确定该问题是增加异常处理器类后，对全局的异常起作用了，如对 Swagger 也起作用了。所以可以在 application 配置里增加 SpringDoc 的配置，防止全局异常处理器的响应定义覆盖所有接口。
application.yml 添加的内容如下所示：
springdoc:
# 防止全局异常处理器的响应定义覆盖所有接口
override-with-generic-response: false
# 禁用损坏引用清理（如遇到 Schema 解析问题可尝试）
remove-broken-reference-definitions: false
