SpringBoot Java 21应用无法生成Swagger API文档问题排查

针对你遇到的访问/api/docs出现404的问题，可按以下步骤排查解决：

1. 修正API文档访问路径 #

SpringDoc的API文档接口默认返回JSON格式，当自定义路径为/api/docs时，需要通过.json后缀访问，即请求http://localhost:8001/api/docs.json。错误提示提到"No static resource api/docs"，说明你的请求被当成静态资源请求处理，而非SpringDoc的接口请求，添加后缀即可正确路由到API文档接口。

2. 验证配置文件格式 #

确保application.yml中SpringDoc的配置层级缩进正确，避免格式错误导致配置不生效：

springdoc:
  api-docs:
    enabled: true
    path: /api/docs
  swagger-ui:
    enabled: false

3. 放行Spring Security拦截（若启用） #

如果应用启用了Spring Security，需要在配置类中放行API文档相关路径，示例代码如下：

@Configuration
@EnableWebSecurity
public class SecurityConfig {
    @Bean
    public SecurityFilterChain securityFilterChain(HttpSecurity http) throws Exception {
        http.authorizeHttpRequests(auth -> auth
                .requestMatchers("/api/docs/**").permitAll()
                .anyRequest().authenticated()
        );
        return http.build();
    }
}

4. 清理冲突依赖 #

确认项目中未引入旧版Swagger/OpenAPI依赖（如springfox系列），这类依赖会与springdoc-openapi产生冲突，若存在需直接移除。

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