Spring Boot 3集成Springdoc-OpenAPI遇404错误求助

1. 确认依赖与同步状态 #

• 检查build.gradle中的依赖拼写无误，执行gradle build --refresh-dependencies强制刷新依赖，避免本地缓存导致依赖未正确引入。
• 多模块项目需确保依赖添加在web业务模块，而非根模块或其他非web模块。

2. 核对访问路径（Spring Boot 3适配变化） #

Spring Boot 3搭配springdoc v2的默认路径已调整：

• Swagger UI默认路径为 http://localhost:8080/swagger-ui/index.html（注意不是旧版的swagger-ui.html）
• 若项目配置了上下文路径（如server.servlet.context-path=/api），需拼接路径访问：http://localhost:8080/api/v3/api-docs 和 http://localhost:8080/api/swagger-ui/index.html

3. 清理无效配置 #

• springdoc.enable-native-support=true仅用于GraalVM原生镜像打包场景，普通Spring Boot项目无需添加，直接删除该配置即可消除JetBrains报错。
• 检查application.properties/application.yml中是否存在springdoc.api-docs.enabled=false或springdoc.swagger-ui.enabled=false，这两个配置默认值为true，若被手动修改会直接导致文档路径404。

4. 排查Spring MVC/Security拦截问题 #

• 若自定义了WebMvcConfigurer，需确保放行Swagger相关资源路径：

  @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/springdoc/");
  }
  

• 若启用了Spring Security，必须添加放行规则：

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

5. 确认Controller扫描范围 #

检查Spring Boot启动类的@SpringBootApplication注解是否覆盖了Controller所在包：

• 若启动类包路径为com.example.app，而Controller在com.example.controller，需添加@ComponentScan(basePackages = "com.example")确保Controller被扫描到，否则springdoc无法识别接口。

6. 查看启动日志定位细节 #

启动项目时重点查看日志：

• 是否有springdoc初始化相关的输出信息
• 是否存在类加载失败、资源找不到等报错，这些日志能直接定位具体异常点

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