配置SpringDoc后无法打开OpenApi(Swagger)页面，请求排查问题

Gradle依赖 #

implementation group: 'org.springdoc', name: 'springdoc-openapi-ui', version: '1.6.13'
implementation group: 'io.swagger.core.v3', name: 'swagger-annotations', version: '2.2.7'   

配置文件（application.properties） #

springdoc.swagger-ui.enabled=true
springdoc.swagger-ui.path=/swagger-ui.html  

控制器代码 #

@RestController
@RequestMapping("/api/v1/cheque")
@FieldDefaults(level = AccessLevel.PRIVATE,makeFinal = true)
public class ChequeController {

    ProductService productService;

    public ChequeController(ProductService productService) {
        this.productService = productService;
    }

    @GetMapping(value = "/get/{id}", produces = "application/json")
    public Optional<Product> getByid(@PathVariable Long id) {
        return productService.getById(id);
    }

    @GetMapping("/test")
    public String test() {
        return "test";
    }
}  

OpenAPI配置类 #

@Configuration
public class OpenApiConfiguration {

    @Bean
    public OpenAPI customOpenAPI() {
        return new OpenAPI()
                .info(
                        new Info()
                                .title("Example Swagger Api")
                                .version("1.0.0")
                );
    }
}

问题描述 #

访问 localhost:8080/swagger-ui.html 时出现404白标错误：

Whitelabel Error Page There was an unexpected error (type=Not Found, status=404).

按官方说明Swagger UI应该自动部署到Spring Boot应用中，求排查配置问题。

排查方案 #

1. 版本兼容性问题 #

springdoc-openapi-ui 1.6.13仅适配Spring Boot 2.6.x版本，如果你使用的是Spring Boot 3.x，必须升级springdoc到2.x系列（比如2.2.0），否则会因依赖不兼容导致UI无法加载。

2. 拦截器/Spring Security拦截路径 #

如果项目中配置了Spring Security或自定义拦截器，默认会拦截Swagger相关的静态资源和接口。需要在配置中放行以下路径：

• /swagger-ui/**
• /v3/api-docs/**
• /swagger-resources/**

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();
    }
}

3. 配置文件生效问题 #

• 确认配置文件放在src/main/resources目录下，位置无误。
• 尝试删除springdoc.swagger-ui.path配置，使用默认路径/swagger-ui/index.html访问，自定义路径可能触发未知问题。

4. 依赖冲突或未正确引入 #

执行gradle dependencies查看依赖树，检查是否存在springfox等其他Swagger相关依赖与springdoc冲突，如有需排除冲突依赖。同时确认springdoc-openapi-ui已成功引入项目。

5. 配置类未被扫描 #

检查OpenApiConfiguration所在包是否在Spring Boot启动类的扫描范围内（@SpringBootApplication默认扫描自身及子包）。若配置类在外部包，需给启动类添加@ComponentScan(basePackages = "配置类所在包路径")指定扫描范围。

内容的提问来源于stack exchange，提问作者стасевич