Spring Boot 3.0.2集成springdoc v2访问index.html遇404错误求助

你的环境信息 #

Spring Boot版本配置：

<parent>
    <groupId>org.springframework.boot</groupId>
    <artifactId>spring-boot-starter-parent</artifactId>
    <version>3.0.2</version>
    <relativePath/> <!-- lookup parent from repository -->
</parent>

SpringDoc依赖配置：

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

Java版本：Corretto 17.0.6

可能的原因及解决方法 #

1. 访问路径错误（最常见） #

SpringDoc v2.x版本的Swagger UI默认访问路径不是/index.html，正确的访问路径是：

• http://localhost:8080/swagger-ui.html
• 或者 http://localhost:8080/swagger-ui/

直接访问/index.html会因为找不到对应静态资源返回404，换上面的路径试试。

2. 自定义WebMvc配置拦截了静态资源 #

如果你的项目中自定义了WebMvcConfigurer实现，检查是否重写了addResourceHandlers方法，确保没有拦截SpringDoc的静态资源。需要添加如下配置放行相关路径：

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

3. 存在依赖冲突 #

检查你的pom.xml中是否同时引入了其他文档工具依赖（比如SpringFox、其他版本的OpenAPI依赖），这些依赖会和springdoc-openapi产生冲突，导致UI资源无法加载。移除多余的文档相关依赖即可。

4. 包扫描范围问题 #

如果Spring Boot主类的包路径不是项目根路径，可能没有扫描到SpringDoc的自动配置类。可以在主类上添加@ComponentScan指定包含org.springdoc的包，或者手动添加@EnableOpenApi注解开启OpenAPI配置：

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

内容的提问来源于stack exchange，提问作者Susana González