Spring Boot 3.4.1集成springdoc-openapi-ui后Swagger UI异常求助

环境信息 #

• Spring Boot版本：2.x.x / 3.x.x（3.4.1）
• springdoc-openapi-ui版本：1.7.0

当前配置 #

pom.xml依赖 #

<dependency>
    <groupId>org.springdoc</groupId>
    <artifactId>springdoc-openapi-ui</artifactId>
    <version>3.4.1</version>
</dependency>

application.properties配置 #

springdoc.api-docs.path=/v3/api-docs
springdoc.swagger-ui.path=/swagger-ui.html

问题现象 #

访问http://localhost:8080/swagger-ui.html时出现以下问题：

• 返回404错误
• 页面加载后显示空白UI
• 不展示API端点

已尝试的排查操作 #

• 验证应用启动无报错
• 检查/v3/api-docs接口不可访问
• 清除浏览器缓存并使用无痕模式访问
• 重新构建项目确保依赖正确导入

解决方案 #

1. 修正依赖版本匹配问题 #

Spring Boot 3.x需要搭配springdoc-openapi v2.x及以上版本，你当前使用的springdoc-openapi-ui 1.7.0仅适配Spring Boot 2.x，版本不兼容是核心问题。

调整pom.xml为Spring Boot 3.x适配的starter依赖：

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

2. 核对配置项正确性 #

Spring Boot 3.x下部分配置逻辑有调整，确保application.properties配置准确：

springdoc.api-docs.path=/v3/api-docs
springdoc.swagger-ui.path=/swagger-ui.html
# 显式开启Swagger UI（默认开启，可避免环境差异导致的关闭）
springdoc.swagger-ui.enabled=true

3. 确保API接口被扫描 #

• 检查Controller类是否添加了@RestController/@Controller注解
• 若Controller不在主启动类的同包或子包下，需在主启动类添加@ComponentScan(basePackages = "你的接口包路径")指定扫描范围
• 可在接口方法上添加@Operation、@Parameter等OpenAPI注解，帮助Swagger识别并展示API详情

4. 排查安全框架拦截 #

如果项目使用Spring Security、Shiro等安全框架，需放行Swagger相关路径：
以Spring Security为例，添加配置类：

@Configuration
public class SecurityConfig {
    @Bean
    public SecurityFilterChain securityFilterChain(HttpSecurity http) throws Exception {
        http.authorizeHttpRequests(auth -> auth
                .requestMatchers("/v3/api-docs/**", "/swagger-ui/**", "/swagger-ui.html")
                .permitAll()
                .anyRequest()
                .authenticated()
        );
        return http.build();
    }
}

5. 验证API文档接口可用性 #

启动应用后先访问http://localhost:8080/v3/api-docs：

• 若能返回JSON格式的API文档数据，说明后端接口正常，问题出在Swagger UI加载逻辑，可尝试重新启动应用或清理浏览器缓存
• 若仍返回404，需检查依赖是否正确导入、配置是否生效

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