访问Swagger UI与API规格YAML文件时出现HTTP 404错误

问题分析 #

从日志能看到，请求/v3/api-docs.yaml被路由到了ResourceHttpRequestHandler，说明springdoc的API文档端点和Swagger UI的Servlet映射根本没生效——权限已经完全放开，排除了安全拦截的问题。

解决方案 #

按以下步骤逐一排查：

1. 修复依赖配置语法错误
   你的pom.xml里最后一个</dependencies>标签写错成了<dependencies>，先修正这个语法问题，确保Maven能正确解析依赖并拉取springdoc的完整包。

2. 强制触发springdoc配置加载
   在Spring Boot启动类上添加@EnableOpenApi注解，手动启用springdoc的自动配置，避免自动配置逻辑被意外屏蔽：

   @SpringBootApplication
   @EnableOpenApi
   public class YourApplication {
       public static void main(String[] args) {
           SpringApplication.run(YourApplication.class, args);
       }
   }
   

3. 排查依赖冲突
   确认项目里没有引入旧版Swagger依赖（比如springfox-swagger2、springfox-swagger-ui），这类依赖会和springdoc产生冲突，直接删除或排除即可。

4. 显式配置springdoc访问路径
   在application.properties中添加以下配置，固定API文档和UI的访问路径：

   springdoc.api-docs.path=/v3/api-docs
   springdoc.swagger-ui.path=/swagger-ui.html
   

   之后重新访问http://localhost:8081/v3/api-docs.yaml（或/v3/api-docs查看JSON格式）、http://localhost:8081/swagger-ui.html测试。

5. 修复自定义WebMvc的资源映射
   如果项目里自定义了WebMvcConfigurer并重写了addResourceHandlers，需要手动添加Swagger UI的静态资源映射，否则UI静态文件会找不到：

   @Configuration
   public class CustomWebMvcConfig implements WebMvcConfigurer {
       @Override
       public void addResourceHandlers(ResourceHandlerRegistry registry) {
           // 保留原有资源映射的同时，添加Swagger UI的映射
           registry.addResourceHandler("/swagger-ui/**")
                   .addResourceLocations("classpath:/META-INF/resources/webjars/swagger-ui/");
       }
   }
   

验证 #

重启项目后，查看启动日志里是否有springdoc相关的初始化日志（比如SpringDocWebMvcConfiguration加载信息），出现这类日志说明配置已生效。

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