升级Spring Boot 3.4.1后springdoc生成OpenAPI JSON失败

核心原因 #

Spring Boot 3.4.x 基于 Spring Framework 6.1.x，而 springdoc-openapi-starter-webmvc-ui 2.2.0 适配的是 Spring Framework 6.0.x 版本的 API。Spring Framework 6.1 中对 ControllerAdviceBean 的单参数构造器做了移除/修改，导致版本不兼容触发 NoSuchMethodError。

解决方案 #

1. 升级 springdoc-openapi 到兼容版本 #

springdoc-openapi 从 2.6.0 开始正式支持 Spring Boot 3.4.x，直接更新依赖：

<!-- Maven 依赖 -->
<dependency>
    <groupId>org.springdoc</groupId>
    <artifactId>springdoc-openapi-starter-webmvc-ui</artifactId>
    <version>2.6.0</version>
</dependency>

// Gradle 依赖
implementation 'org.springdoc:springdoc-openapi-starter-webmvc-ui:2.6.0'

2. 排查并清理依赖冲突 #

执行命令检查依赖树，确认是否有旧版 Spring Framework 组件被间接引入：

# Maven 命令
mvn dependency:tree
# Gradle 命令
./gradlew dependencies

如果发现 spring-web/spring-context 存在 6.0.x 版本，在 springdoc 依赖中排除冲突：

<dependency>
    <groupId>org.springdoc</groupId>
    <artifactId>springdoc-openapi-starter-webmvc-ui</artifactId>
    <version>2.6.0</version>
    <exclusions>
        <exclusion>
            <groupId>org.springframework</groupId>
            <artifactId>spring-web</artifactId>
        </exclusion>
    </exclusions>
</dependency>

3. 简化 ControllerAdvice 配置 #

确保异常处理类使用框架默认扫描机制，避免手动初始化 ControllerAdviceBean：

@RestControllerAdvice
public class GlobalExceptionHandler {
    @ExceptionHandler(Exception.class)
    public ResponseEntity<ErrorResponse> handleGenericException(Exception ex) {
        return ResponseEntity.status(HttpStatus.INTERNAL_SERVER_ERROR)
                .body(new ErrorResponse(ex.getMessage()));
    }

    // 内部错误响应类
    private static class ErrorResponse {
        private String message;
        public ErrorResponse(String message) { this.message = message; }
        public String getMessage() { return message; }
    }
}

参考信息 #

异常堆栈示例 #

java.lang.NoSuchMethodError: 'void org.springframework.web.method.ControllerAdviceBean.<init>(java.lang.Object)'
    at org.springdoc.webmvc.api.OpenApiResource.initControllerAdviceBeans(OpenApiResource.java:456)
    at org.springdoc.webmvc.api.OpenApiResource.getOpenApi(OpenApiResource.java:193)
    at org.springdoc.webmvc.api.OpenApiResource.openapiJson(OpenApiResource.java:144)
    at java.base/jdk.internal.reflect.NativeMethodAccessorImpl.invoke0(Native Method)
    at java.base/jdk.internal.reflect.NativeMethodAccessorImpl.invoke(NativeMethodAccessorImpl.java:77)
    at java.base/jdk.internal.reflect.DelegatingMethodAccessorImpl.invoke(DelegatingMethodAccessorImpl.java:43)
    at java.base/java.lang.reflect.Method.invoke(Method.java:568)
    at org.springframework.web.method.support.InvocableHandlerMethod.doInvoke(InvocableHandlerMethod.java:207)
    // 省略后续堆栈内容

原异常处理类示例 #

@ControllerAdvice
public class CustomExceptionHandler {
    @ExceptionHandler(IllegalArgumentException.class)
    public ResponseEntity<String> handleIllegalArgument(IllegalArgumentException ex) {
        return ResponseEntity.badRequest().body(ex.getMessage());
    }
}

内容的提问来源于stack exchange，提问作者garmoshka