springdoc-openapi-ui无法访问Swagger界面？

Question

使用 springdoc-openapi-ui 时，常见问题是应用启动后无法访问 Swagger UI 界面（如 http://localhost:8080/swagger-ui.html 或 /swagger-ui/index.html），页面返回 404 错误。该问题通常由依赖版本不兼容、WebMvc 配置冲突或路径映射错误导致。例如，Spring Boot 3.x 需使用 springdoc-openapi-starter-webmvc-ui，且默认 UI 路径为 /swagger-ui/index.html。此外，若配置了拦截器或安全规则（如 Spring Security）未放行相关路径，也会导致访问被拒。需检查依赖引入、自动配置是否生效及安全配置中对 /swagger-ui/** 和 /v3/api-docs/** 的放行设置。

Answer 1

使用 springdoc-openapi-ui 时无法访问 Swagger UI 的深度解析与解决方案

1. 问题背景与现象描述

在基于 Spring Boot 构建的 RESTful API 项目中，集成 springdoc-openapi-ui 是生成 OpenAPI 文档并提供可视化界面（Swagger UI）的主流方式。然而，许多开发者在应用启动后尝试访问 http://localhost:8080/swagger-ui.html 或 /swagger-ui/index.html 时，会遭遇 HTTP 404 错误。

该问题虽表象简单，但背后可能涉及多个技术层次的配置冲突或版本不兼容，尤其在升级到 Spring Boot 3.x 后更为常见。

2. 常见原因分类分析

• 依赖版本不匹配：Spring Boot 3.x 使用 Java 17+ 和 Jakarta EE 9+，需使用新的坐标 springdoc-openapi-starter-webmvc-ui，而非旧版 springdoc-openapi-ui。
• 默认路径变更：Spring Boot 3 中默认 UI 路径为 /swagger-ui/index.html，而不再是 /swagger-ui.html。
• WebMvc 配置干扰：自定义 WebMvcConfigurer 可能覆盖了静态资源映射规则。
• 安全框架拦截：Spring Security 或 Shiro 未放行 /swagger-ui/** 和 /v3/api-docs/** 路径。
• 自动配置失效：条件化配置未满足，导致 OpenApiResource 未被加载。

3. 版本兼容性对照表

Spring Boot 版本	推荐依赖坐标	默认 UI 路径	注意事项
< 3.0	io.springfox:springfox-swagger2 + ui	/swagger-ui.html	已过时，建议迁移
2.x	org.springdoc:springdoc-openapi-ui	/swagger-ui.html	支持 WebFlux 和 MVC
≥ 3.0	org.springdoc:springdoc-openapi-starter-webmvc-ui	/swagger-ui/index.html	Jakarta 包名，注意模块路径

4. 典型错误配置示例

<dependency>
    <groupId>org.springdoc</groupId>
    <artifactId>springdoc-openapi-ui</artifactId>
    <version>1.6.14</version> <!-- 不适用于 Spring Boot 3 -->
</dependency>
    

上述依赖在 Spring Boot 3 环境下会导致自动配置不生效，因为其仍基于 javax.servlet，无法适配 Jakarta EE。

5. 正确依赖引入方式（Spring Boot 3 示例）

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

此依赖内置了对 Jakarta Servlet 的支持，并自动注册 Swagger UI 静态资源处理器。

6. 安全配置中的路径放行（Spring Security）

若项目集成了 Spring Security，必须显式放行文档相关路径：

@Configuration
@EnableWebSecurity
public class SecurityConfig {

    @Bean
    public SecurityFilterChain filterChain(HttpSecurity http) throws Exception {
        http.authorizeHttpRequests(authz -> authz
            .requestMatchers("/swagger-ui/**", "/v3/api-docs/**", "/webjars/**").permitAll()
            .anyRequest().authenticated()
        );
        return http.build();
    }
}
    

7. 自定义 WebMvcConfigurer 的潜在冲突

当实现 WebMvcConfigurer 并重写 addResourceHandlers 时，若未调用父类逻辑或遗漏配置，可能导致静态资源无法映射。

正确做法是保留默认资源处理器：

@Override
public void addResourceHandlers(ResourceHandlerRegistry registry) {
    registry.addResourceHandler("/swagger-ui/**")
            .addResourceLocations("classpath:/META-INF/resources/webjars/springdoc-openapi-ui/");
    registry.addResourceHandler("/**")
            .addResourceLocations("classpath:/static/");
}
    

8. 启动日志验证自动配置状态

检查应用启动日志中是否包含以下关键信息：

:: SpringDoc :: Loaded OpenAPI v3 definition: springfox.documentation.spring.web.plugins.DocumentationPluginsBootstrapper
:: SpringDoc :: Found springdoc-openapi web mvc config beans.
:: SpringDoc :: Enabled=true, Management Context Enabled=false
    

若无此类日志输出，说明自动配置未触发，需检查依赖或组件扫描范围。

9. 路径映射调试流程图

graph TD
            A[应用启动] --> B{依赖正确?}
            B -- 否 --> C[更换为 starter-webmvc-ui]
            B -- 是 --> D{路径是否变更?}
            D -- /swagger-ui.html --> E[改为 /swagger-ui/index.html]
            D -- /swagger-ui/index.html --> F{Security 放行?}
            F -- 否 --> G[添加 permitAll() 规则]
            F -- 是 --> H{WebMvc 配置冲突?}
            H -- 是 --> I[检查 addResourceHandlers]
            H -- 否 --> J[访问成功]

10. 高级排查建议

• 使用 curl http://localhost:8080/v3/api-docs 验证 API 定义是否生成。
• 通过 @ConditionalOnMissingBean 判断是否存在手动覆盖的 OpenAPI 配置。
• 启用 debug=true 查看自动配置报告。
• 检查 management.endpoints.web.exposure.include=* 是否影响端点暴露。
• 确认打包方式（jar/war）是否影响资源路径解析。
• 使用 Actuator 的 /conditions 端点查看 SpringDocAutoConfiguration 的匹配状态。
• 避免使用 @EnableWebMvc，除非有强定制需求。
• 考虑使用 springdoc.swagger-ui.path 自定义 UI 路径。
• 验证 classpath 下是否存在 META-INF/resources/webjars/springdoc-openapi-ui/ 目录。
• 在 IDE 中执行 mvn dependency:tree | grep springdoc 检查依赖树。