本文记录了在 JDK 21 和 Spring Boot 3.x 环境下整合 Knife4j (Swagger3) 的关键步骤与常见问题。主要涉及依赖选择（需使用 Jakarta 命名空间版本）、配置文件编写（OpenAPI 自定义及分组）、以及启动报错处理。针对 NoSuchMethodError 和 Bean 冲突问题，提供了通过 springdoc 配置项 override-with-generic-response 解决的方法。适用于需要快速搭建 API 文档且避免常见坑点的开发者。
使用 JDK 21 版本创建的 Spring Boot 项目，在 SpringBoot3 整合 Swagger3 过程中遇到一些问题。网上很多关于 SpringBoot3 整合 Knife4j(Swagger3) 的步骤完全照着做会有很多兼容性问题。现将遇到的问题及解决方案记录如下。
Spring Boot 3.x 必须使用 knife4j-openapi3-jakarta（Jakarta 命名空间）。
com.github.xiaoymin
knife4j-openapi3-jakarta-spring-boot-starter
4.5.0
注意：不要使用旧版本的 knife4j-spring-boot-starter，否则会出现兼容性问题。
SpringBoot3.x 相比 SpringBoot2.x 特性上有很大改变，必须选择 SpringBoot3.x 版本兼容的 Knife4j 版本。
创建配置类以自定义 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 String API_INFO_TITLE = "软件接口文档";
private static final String API_INFO_VERSION = "V1.0";
private static final String API_INFO_DESCRIPTION = "Api 接口列表";
private static final String API_INFO_LICENSE = "Apache License 2.0";
private static final String API_INFO_EMAIL = "[email protected]";
private static final String API_INFO_NAME = "Admin";
// xxx1 模块
@Bean
public GroupedOpenApi api4() {
return GroupedOpenApi.builder()
.group("regularGrade-module-api")
.displayName("平时成绩模块接口")
.packagesToScan("com.call.controller.regularGrade")
.addOpenApiCustomizer(this::setCustomStatusCode)
.build();
}
// 智能评分模块
@Bean
public GroupedOpenApi api3() {
return GroupedOpenApi.builder()
.group("IntelligentScoring-module-api")
.displayName("智能评分模块接口")
.packagesToScan("com.call.controller.intelligentScoring")
.addOpenApiCustomizer(this::setCustomStatusCode)
.build();
}
// AI 大模型 Agent 接口
@Bean
public GroupedOpenApi api2() {
return GroupedOpenApi.builder()
.group("aiagent-module-api")
.displayName("AI 大模型 Agent 接口")
.packagesToScan("com.ai.LangChain4j.agent2.DeclarativeAPI")
.addOpenApiMethodFilter(method -> method.isAnnotationPresent(io.swagger.v3.oas.annotations.Operation.class))
.addOpenApiCustomizer(this::setCustomStatusCode)
.build();
}
@Bean
public OpenAPI openAPI() {
return new OpenAPI()
.info(new Info()
.title(API_INFO_TITLE)
.description(API_INFO_DESCRIPTION)
.version(API_INFO_VERSION)
.contact(new Contact().name(API_INFO_NAME).email(API_INFO_EMAIL))
.license(new License().name(API_INFO_LICENSE).url(SERVICE_URL)));
}
/**
* 设置自定义错误码
*
* @param openApi openApi 对象
*/
private void setCustomStatusCode(OpenAPI openApi) {
if (openApi.getPaths() != null) {
Paths paths = openApi.getPaths();
for (Map.Entry<String, PathItem> entry : paths.entrySet()) {
String key = entry.getKey();
PathItem value = entry.getValue();
Operation put = value.getPut();
Operation get = value.getGet();
Operation delete = value.getDelete();
Operation post = value.getPost();
if (put != null) {
put.setResponses(handleResponses(put.getResponses()));
}
if (get != null) {
get.setResponses(handleResponses(get.getResponses()));
}
if (delete != null) {
delete.setResponses(handleResponses(delete.getResponses()));
}
if (post != null) {
post.setResponses(handleResponses(post.getResponses()));
}
}
}
}
/**
* 处理不同请求方式中的自定义响应码
*
* @param responses 响应体集合
* @return 返回处理后的响应体集合
*/
private ApiResponses handleResponses(ApiResponses responses) {
Content content = new Content();
for (Map.Entry<String, ApiResponse> entry : responses.entrySet()) {
String key = entry.getKey();
ApiResponse apiResponse = entry.getValue();
if (apiResponse != null) {
content = apiResponse.getContent();
break;
}
}
Map<Integer, String> map = StatusCode.toMap();
for (Map.Entry<Integer, String> entry : map.entrySet()) {
ApiResponse api = new ApiResponse();
api.setContent(content);
api.description(entry.getValue());
responses.addApiResponse(entry.getKey() + "", api);
}
return responses;
}
/**
* 根据@Tag 上的排序，写入 x-order
*
* @return the global open api customizer
*/
@Bean
public GlobalOpenApiCustomizer orderGlobalOpenApiCustomizer() {
return openApi -> {
if (openApi.getTags() != null) {
openApi.getTags().forEach(tag -> {
Map<String, Object> map = new HashMap<>();
map.put("x-order", RandomUtil.randomInt(0, 100));
tag.setExtensions(map);
});
}
if (openApi.getPaths() != null) {
openApi.addExtension("x-test123", "333");
openApi.getPaths().addExtension("x-abb", RandomUtil.randomInt(1, 100));
}
};
}
@Bean
public OpenAPI customOpenAPI() {
return new OpenAPI()
.info(new Info()
.title("AI 大模型 API")
.version("1.0")
.description("Knife4j 集成 springdoc-openapi")
.termsOfService("http://doc.xiaominfo.com")
.license(new License().name("Apache 2.0")
.url("http://doc.xiaominfo.com")));
}
}
启动成功，访问：http://localhost:8886/doc.html
页面效果如图：
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）：
# 配置 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
# 是否显示页脚
enable-footer: false
# 启用自定义页脚内容
enable-footer-custom: true
# 设置自定义页脚的内容
footer-custom-content: Apache License 2.0
# 是否启用动态参数
enable-dynamic-parameter: false
# 启用调试模式
enable-debug: true
# 启用 OpenAPI 3.0 的支持
enable-open-api: false
# 启用接口分组功能
enable-group: true
# 是否启用 CORS 跨域支持
cors: false
# 是否启用生产模式
production: false
# 配置基本的认证信息
basic:
enable: false
username: admin
password: 123
springdoc:
override-with-generic-response: false
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
目前启动时会报如下错误（暂时未解决）：
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.
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
微信公众号「极客日志」，在微信中扫描左侧二维码关注。展示文案：极客日志 zeeklog
查找任何按下的键的javascript键代码、代码、位置和修饰符。 在线工具，Keycode 信息在线工具，online
JavaScript 字符串转义/反转义；Java 风格 \uXXXX（Native2Ascii）编码与解码。 在线工具，Escape 与 Native 编解码在线工具，online
使用 Prettier 在浏览器内格式化 JavaScript 或 HTML 片段。 在线工具，JavaScript / HTML 格式化在线工具，online
Terser 压缩、变量名混淆，或 javascript-obfuscator 高强度混淆（体积会增大）。 在线工具，JavaScript 压缩与混淆在线工具，online
生成新的随机RSA私钥和公钥pem证书。 在线工具，RSA密钥对生成器在线工具，online
基于 Mermaid.js 实时预览流程图、时序图等图表，支持源码编辑与即时渲染。 在线工具，Mermaid 预览与可视化编辑在线工具，online