Spring Boot集成springdoc-openapi时Swagger UI出现404错误求助

问题描述 #

为Spring Boot应用添加Swagger UI后，访问swagger-ui.html时出现404错误，相关配置及错误信息如下：

配置类 #

@Configuration
public class SwaggerConfig {

    @Bean
    public OpenAPI springShopOpenAPI() {
        return new OpenAPI()
                .info(new Info().title("JOYAS-STOCK API Docs")
                        .description("JOYAS-STOCK REST API documentation")
                        .version("v1.0.0"));
    }
}

application.properties配置 #

#swagger-ui config
springdoc.swagger-ui.path=/swagger-ui
springdoc.swagger-ui.operationsSorter=method
springdoc.swagger-ui.tagsSorter=alpha

pom.xml依赖 #

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

错误信息 #

白标错误页面
此应用没有针对/error的显式映射，所以您看到的是默认回退页面。

发生意外错误（类型=未找到，状态=404）。

解决方案 #

• 修正访问路径：你在配置中设置了springdoc.swagger-ui.path=/swagger-ui，因此正确的访问路径是/swagger-ui，而非传统Swagger2的/swagger-ui.html。直接访问应用域名+端口+/swagger-ui即可打开UI页面。

• 检查依赖兼容性：springdoc-openapi-ui 1.6.13适配Spring Boot 2.6.x版本，如果你的Spring Boot版本高于2.7.x，建议升级springdoc依赖到对应版本（比如Spring Boot 3.x需使用springdoc-openapi v2.x系列）；若版本过低，也可能导致无法加载。

• 确认配置类生效：确保SwaggerConfig类所在包被Spring Boot扫描到——要么和主启动类同包/子包，要么通过@ComponentScan注解指定扫描该类所在包。

• 放行Swagger相关路径（若有安全框架）：如果应用集成了Spring Security或自定义拦截器，需允许访问Swagger相关资源路径，示例Spring Security配置：

@Configuration
public class SecurityConfig extends WebSecurityConfigurerAdapter {
    @Override
    protected void configure(HttpSecurity http) throws Exception {
        http.authorizeRequests()
                .antMatchers("/swagger-ui/**", "/v3/api-docs/**")
                .permitAll()
                .anyRequest()
                .authenticated();
    }
}

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