Spring Boot 2.5.6升级至3.2.5后Swagger UI失效问题咨询

核心结论 #

升级到Spring Boot 3.x后不需要强制引入Spring Security，问题主要出在Swagger依赖的兼容性和配置细节上。

问题根源 #

Spring Boot 3.x基于Jakarta EE API，旧版SpringFox（Swagger2）依赖仍使用Java EE API，二者不兼容。必须替换为适配Jakarta EE的SpringDoc OpenAPI（Swagger官方推荐的替代方案）。

具体修复步骤 #

1. 替换依赖

移除项目中所有SpringFox相关依赖（如springfox-boot-starter、springfox-swagger2等），添加SpringDoc的starter依赖：

<!-- Maven -->
<dependency>
    <groupId>org.springdoc</groupId>
    <artifactId>springdoc-openapi-starter-webmvc-ui</artifactId>
    <version>2.2.0</version> <!-- 适配Spring Boot 3.2.x -->
</dependency>

// Gradle
implementation 'org.springdoc:springdoc-openapi-starter-webmvc-ui:2.2.0'

2. 调整Swagger配置（可选但推荐）

原有SwaggerConfig大部分代码可复用，建议简化为Builder模式（更简洁），注意类包路径仍为io.swagger.v3.oas.models：

@Configuration
public class SwaggerConfig {

    @Value("${spring.application.name}")
    private String applicationId;

    @Value("${spring.application.description}")
    private String description;

    @Value("${spring.application.version}")
    private String version;

    @Value("${app.env}")
    private String env;

    @Bean
    public OpenAPI openAPI() {
        return new OpenAPI()
                .info(new Info()
                        .title(env + " - " + applicationId)
                        .description(description)
                        .version(version))
                .components(new Components());
    }
}

若无需自定义组件，components(new Components())可直接省略。

3. 验证访问路径

SpringDoc默认Swagger UI访问路径为：http://localhost:8080/swagger-ui/index.html（旧版SpringFox为/swagger-ui.html），如需修改路径，可在application.properties中配置：

springdoc.swagger-ui.path=/swagger-ui.html

4. 排除路径拦截（如有自定义Web配置）

若项目存在WebMvcConfigurer或其他拦截器，需放行以下路径：

• /swagger-ui/**
• /v3/api-docs/**
• /swagger-resources/**

示例配置：

@Configuration
public class WebConfig implements WebMvcConfigurer {
    @Override
    public void addResourceHandlers(ResourceHandlerRegistry registry) {
        registry.addResourceHandler("/swagger-ui/**")
                .addResourceLocations("classpath:/META-INF/resources/webjars/springdoc-openapi-ui/");
        registry.addResourceHandler("/v3/api-docs/**")
                .addResourceLocations("classpath:/META-INF/resources/");
    }
}

5. 检查Java版本

Spring Boot 3.x要求Java 17及以上，确保项目运行环境符合要求。

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