SpringBoot集成Swagger出现Whitelabel Error Page 404错误求助

1. 依赖版本不匹配或缺失 #

• 不同SpringBoot版本对应不同的Swagger生态依赖，别混着用：
  • SpringBoot 2.x 用传统Swagger：springfox-swagger2 + springfox-swagger-ui
  • SpringBoot 3.x 必须用SpringDoc OpenAPI（Swagger官方替代）：springdoc-openapi-starter-webmvc-ui
• 示例配置：
  SpringBoot 2.x：

  dependencies {
      implementation 'io.springfox:springfox-swagger2:2.9.2'
      implementation 'io.springfox:springfox-swagger-ui:2.9.2'
  }
  

  SpringBoot 3.x：

  dependencies {
      implementation 'org.springdoc:springdoc-openapi-starter-webmvc-ui:2.2.0'
  }
  

2. 配置类细节错误 #

• SpringBoot 2.x 必须给配置类加@Configuration和@EnableSwagger2，同时确保basePackage指向你的控制器所在包：

  @Configuration
  @EnableSwagger2
  public class SwaggerConfig {
      @Bean
      public Docket api() {
          return new Docket(DocumentationType.SWAGGER_2)
                  .select()
                  .apis(RequestHandlerSelectors.basePackage("com.yourproject.controller"))
                  .paths(PathSelectors.any())
                  .build();
      }
  }
  

• SpringBoot 3.x 不需要@EnableSwagger2，直接配置OpenAPI bean即可：

  @Configuration
  public class SwaggerConfig {
      @Bean
      public OpenAPI customOpenAPI() {
          return new OpenAPI()
                  .info(new Info().title("Club API")
                          .version("1.0")
                          .description("Club management API docs"));
      }
  }
  

3. 访问路径搞错了 #

• SpringBoot 2.x Swagger UI默认地址：http://localhost:端口号/swagger-ui.html
• SpringBoot 3.x SpringDoc UI默认地址：http://localhost:端口号/swagger-ui/index.html 或简化为 http://localhost:端口号/swagger-ui/
• 确认端口号和项目配置一致，别用错端口。

4. 静态资源被拦截 #

• 如果用了Spring Security或自定义WebMvcConfigurer，必须放行Swagger相关资源：
  Spring Security 放行示例：

  @Override
  protected void configure(HttpSecurity http) throws Exception {
      http.authorizeRequests()
              // SpringBoot 2.x 路径
              .antMatchers("/swagger-ui/**", "/v2/api-docs", "/swagger-resources/**", "/webjars/**")
              // SpringBoot 3.x 替换成下面的路径
              // .antMatchers("/swagger-ui/**", "/v3/api-docs/**")
              .permitAll()
              .anyRequest().authenticated();
  }
  

  WebMvc 静态资源配置：

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

5. 包扫描范围没覆盖到 #

• 确保Swagger配置类所在的包被SpringBoot主类扫描到，主类的@SpringBootApplication默认扫描同包及子包，如果配置类在其他包，要加@ComponentScan指定：

  @SpringBootApplication
  @ComponentScan(basePackages = {"com.yourproject.config", "com.yourproject.controller"})
  public class ClubApplication {
      public static void main(String[] args) {
          SpringApplication.run(ClubApplication.class, args);
      }
  }
  

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