Spring Boot 3中Swagger UI无法访问（404）问题求助

核心问题点 #

Spring Boot 3.x 搭配 springdoc-openapi 2.x 版本时，Swagger UI的默认入口路径已经从swagger-ui.html变更为swagger-ui/index.html，这是导致404最常见的原因。

具体排查步骤 #

• 优先验证新路径：直接访问 http://localhost:8080/swagger-ui/index.html，大部分情况换这个路径就能解决问题。
• 检查依赖有效性：确认项目依赖没有冲突，比如不要同时引入旧版springfox或重复的springdoc依赖。正确的pom依赖示例：

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

• 放行Swagger相关路径：如果项目使用Spring Security或自定义WebMvc配置，需确保Swagger资源不被拦截：
  • Spring Security配置示例：

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

  • 自定义WebMvc配置时，需添加资源映射：

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

• 核对上下文路径：如果application.properties/yml中配置了server.servlet.context-path，访问时必须加上这个前缀，比如http://localhost:8080/你的上下文路径/swagger-ui/index.html。
• 检查启动日志：查看启动日志中是否有SpringDoc相关初始化信息，如果完全没有，说明依赖未生效，需检查依赖引入是否正确、项目包扫描范围是否覆盖SpringDoc的配置类。

内容的提问来源于stack exchange，提问作者Enes Körhan