Spring Boot集成springdoc-openapi访问Swagger UI返回404如何解决

已确认的前置配置 #

• 已引入Maven依赖：org.springdoc:springdoc-openapi-ui:1.6.9
• 已在Spring Security配置中添加部分Swagger路径放行规则
• 已在启动类添加@OpenAPIDefinition注解
• 访问地址：http://localhost:8080/swagger-ui/index.html

排查步骤与修复方案 #

按优先级从高到低逐一验证：

• 检查SpringMVC静态资源配置是否失效
  这是该类问题最高发的原因：如果项目中存在自定义WebMvcConfigurer配置重写了addResourceHandlers方法、或者直接继承了WebMvcConfigurationSupport类，会导致SpringBoot默认的静态资源映射规则失效，Swagger的前端静态资源无法被正常解析。
  修复方式：手动添加Swagger静态资源映射规则

  @Override
  public void addResourceHandlers(ResourceHandlerRegistry registry) {
      // 保留你原有的其他资源映射配置
      registry.addResourceHandler("/swagger-ui/**")
              .addResourceLocations("classpath:/META-INF/resources/webjars/springdoc-openapi-ui/")
              .resourceChain(false);
  }
  

  如果项目用了继承WebMvcConfigurationSupport的写法，建议改为实现WebMvcConfigurer接口，避免全局自动配置失效。

• 补全Spring Security放行路径，检查自定义过滤器逻辑
  当前的安全配置放行路径不全，且未校验自定义JWT过滤器是否绕过了白名单路径：

  • 首先补全所有Swagger相关的放行路径，修正后的antMatchers列表如下：

  .antMatchers(
      "/auth/**",
      "/swagger-ui.html",
      "/swagger-ui/**",
      "/v3/api-docs/**",
      "/v3/api-docs.yaml",
      "/swagger-resources/**",
      "/webjars/**"
  ).permitAll()
  

  • 检查自定义的jwtAuthenticationFilter逻辑：确保过滤器执行时先判断当前请求路径是否在放行列表中，对白名单路径直接放行，不要执行token校验逻辑，否则静态资源请求会被过滤器拦截返回异常状态码。

• 核对服务访问路径配置

  • 检查配置文件中是否配置了server.servlet.context-path，如果配置了自定义上下文路径，访问地址需要加上对应前缀，例如配置server.servlet.context-path=/dms时，实际访问地址为http://localhost:8080/dms/swagger-ui/index.html
  • 检查是否配置了springdoc.swagger-ui.path、springdoc.api-docs.path自定义路径，如果有配置需要使用自定义后的地址访问。

• 校验依赖兼容性与完整性

  • 如果项目使用SpringBoot 3.x版本，springdoc-openapi-ui 1.6.9完全不兼容，需要替换为2.x版本的springdoc-openapi-starter-webmvc-ui依赖
  • 执行mvn dependency:tree命令查看依赖树，确认springdoc-openapi-ui没有被其他依赖排除、不存在版本冲突。

• 检查启动日志与扫描路径配置

  • 启动项目时搜索控制台日志中springdoc相关的报错，常见的有类扫描失败、接口解析报错，这类初始化异常会导致Swagger端点无法正常注册
  • 可以在配置文件中明确指定Swagger扫描的Controller包路径，避免扫描失败：

  springdoc:
    packages-to-scan: com.yourpackage.dms.controller # 替换为你项目实际的controller包路径
  

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