Spring Boot配置OpenAPI 3时/swagger-ui.html端点报404错误求助

核心原因与解决方案 #

• 端点路径变更：你使用的springdoc-openapi-starter-webmvc-ui 2.x版本（适配Spring Boot 3），Swagger UI的默认访问端点已不再是/swagger-ui.html，改为以下两个路径：

  • http://localhost:8080/swagger-ui/（末尾需带斜杠）
  • http://localhost:8080/swagger-ui/index.html

• 依赖版本优化：当前使用的2.0.0-M4是里程碑版本，存在潜在不稳定问题，建议替换为同分支稳定版，比如2.2.0：

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

• 静态资源放行配置：如果项目配置了Spring Security或自定义资源拦截器，必须放行Swagger相关资源：
  1. 若使用WebMvc自定义配置：

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

2. 若使用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();
}

• Spring Boot版本兼容性检查：springdoc-openapi-starter-webmvc-ui 2.x仅适配Spring Boot 3.x；如果你的项目是Spring Boot 2.x，需改用1.x分支的springdoc-openapi-ui依赖，此时端点仍为/swagger-ui.html：

<dependency>
    <groupId>org.springdoc</groupId>
    <artifactId>springdoc-openapi-ui</artifactId>
    <version>1.6.15</version>
</dependency>

内容的提问来源于stack exchange，提问作者Akhil S Nair