Spring Boot 3中springdoc-openapi与openapi-generator插件启动兼容问题

问题根源 #

1. 依赖冲突：openapi-generator-maven-plugin默认引入的OpenAPI核心依赖（如swagger-core、swagger-models）与springdoc-openapi的版本不兼容，导致类加载时出现反射异常。
2. Security拦截：Spring Security配置未放行Swagger/OpenAPI的相关端点，初始化时无法解析对应的HandlerMapping类。

解决步骤 #

1. 排除openapi-generator的冲突依赖

在pom.xml中给openapi-generator-maven-plugin添加依赖排除，移除与springdoc冲突的模块：

<plugin>
    <groupId>org.openapitools</groupId>
    <artifactId>openapi-generator-maven-plugin</artifactId>
    <!-- 保持你当前使用的插件版本 -->
    <version>你的版本号</version>
    <executions>
        <!-- 你的执行配置 -->
    </executions>
    <dependencies>
        <dependency>
            <groupId>org.openapitools</groupId>
            <artifactId>openapi-generator</artifactId>
            <version>你的版本号</version>
            <exclusions>
                <exclusion>
                    <groupId>io.swagger.core.v3</groupId>
                    <artifactId>swagger-core</artifactId>
                </exclusion>
                <exclusion>
                    <groupId>io.swagger.core.v3</groupId>
                    <artifactId>swagger-models</artifactId>
                </exclusion>
            </exclusions>
        </dependency>
    </dependencies>
</plugin>

执行mvn dependency:tree检查依赖树，确保无重复的OpenAPI核心依赖。

2. 升级springdoc到兼容Spring Boot3的稳定版

将springdoc依赖更新至最新兼容版本（推荐2.2.0及以上）：

<dependency>
    <groupId>org.springdoc</groupId>
    <artifactId>springdoc-openapi-starter-webmvc-ui</artifactId>
    <version>2.2.0</version>
</dependency>

3. 修改Security配置，放行Swagger端点

在EndpointsConstants中新增Swagger允许的端点：

public class EndpointsConstants {
    // 原有常量
    public static final String[] GENERAL_ALLOWED_ENDPOINTS = {"/api/v1/auth/**", "/health"};
    public static final String[] USER_ALLOWED_ENDPOINTS = {"/api/v1/users/**"};
    // Swagger相关放行端点
    public static final String[] SWAGGER_ALLOWED_ENDPOINTS = {
        "/swagger-ui/**",
        "/swagger-ui.html",
        "/v3/api-docs/**",
        "/swagger-resources/**",
        "/webjars/**"
    };
}

然后在SecurityConfig的filterChain方法中添加放行规则：

@Bean
public SecurityFilterChain filterChain(HttpSecurity http) throws Exception {
    http.addFilterBefore(new JwtFilter(jwtProvider, userDetailsService), UsernamePasswordAuthenticationFilter.class);
    http.cors().and()
            .csrf(AbstractHttpConfigurer::disable)
            .httpBasic(AbstractHttpConfigurer::disable)
            .sessionManagement(manager -> manager.sessionCreationPolicy(STATELESS))
            .authenticationProvider(authenticationProvider())
            .authorizeHttpRequests(request -> request
                    .requestMatchers(EndpointsConstants.GENERAL_ALLOWED_ENDPOINTS).permitAll()
                    .requestMatchers(EndpointsConstants.USER_ALLOWED_ENDPOINTS).permitAll()
                    .requestMatchers(EndpointsConstants.SWAGGER_ALLOWED_ENDPOINTS).permitAll() // 新增该行
                    .anyRequest().authenticated());
    return http.build();
}

4. 清理并重建项目

执行命令清理缓存并重新构建：

mvn clean install -U

验证 #

启动应用后访问/swagger/index.html，确认OpenAPI文档正常加载，应用无启动异常。

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