Spring Boot 3.1.0集成Springdoc 2.1.0无API定义问题求助

1. 检查依赖完整性与冲突 #

确保pom.xml中springdoc依赖配置正确，彻底清理残留的springfox相关依赖：

<!-- 核心WebMVC UI依赖 -->
<dependency>
    <groupId>org.springdoc</groupId>
    <artifactId>springdoc-openapi-starter-webmvc-ui</artifactId>
    <version>2.1.0</version>
</dependency>
<!-- 若使用Spring Security，需补充API依赖 -->
<dependency>
    <groupId>org.springdoc</groupId>
    <artifactId>springdoc-openapi-starter-webmvc-api</artifactId>
    <version>2.1.0</version>
</dependency>

执行mvn dependency:tree命令，排查是否存在springfox相关依赖，如有则通过<exclusions>标签排除。

2. 简化自定义配置类 #

Spring Boot 3+环境下springdoc多数配置可自动生效，暂时注释或简化自定义的Swagger配置类，仅保留基础文档信息配置：

@Configuration
public class OpenApiConfig {
    @Bean
    public OpenAPI customOpenAPI() {
        return new OpenAPI()
                .info(new Info().title("业务API文档")
                        .version("1.0")
                        .description("接口功能描述"));
    }
}

避免添加多余的路径扫描、过滤规则，防止干扰自动扫描逻辑。

3. 核对配置文件参数 #

确保application.properties/application.yml中springdoc配置无错误：

# 启用API文档生成
springdoc.api-docs.enabled=true
# 启用Swagger UI界面
springdoc.swagger-ui.enabled=true
# 无需手动指定config-url，默认路径为/v3/api-docs

若项目配置了上下文路径，访问Swagger UI时需使用{context-path}/swagger-ui.html，API文档接口对应{context-path}/v3/api-docs。

4. 验证Controller注解与路径 #

确认Controller类标注@RestController，方法使用明确的请求方法注解（@GetMapping/@PostMapping等），避免仅使用@RequestMapping却未指定请求方法：

@RestController
@RequestMapping("/api/users")
public class UserController {
    @GetMapping("/{id}")
    public ResponseEntity<User> getUserDetail(@PathVariable Long id) {
        // 业务逻辑实现
        return ResponseEntity.ok(new User());
    }
}

同时检查是否误加@Hidden注解到Controller类或方法，该注解会导致接口被排除在文档外。

5. 放行Swagger相关路径（Spring Security场景） #

若项目集成Spring Security，需在安全配置中放行swagger相关路径：

@Configuration
public class SecurityConfig {
    @Bean
    public SecurityFilterChain securityFilterChain(HttpSecurity http) throws Exception {
        http.authorizeHttpRequests(auth -> auth
                .requestMatchers("/v3/api-docs/**", "/swagger-ui/**", "/swagger-ui.html")
                .permitAll()
                .anyRequest().authenticated()
        );
        // 若启用CSRF，需对swagger路径关闭防护或配置令牌传递
        http.csrf(csrf -> csrf.ignoringRequestMatchers("/v3/api-docs/**", "/swagger-ui/**"));
        return http.build();
    }
}

6. 直接验证API文档接口 #

先访问http://localhost:8080/v3/api-docs（带上下文路径则追加前缀），若返回JSON格式的API定义，说明问题出在Swagger UI加载环节；若返回404，说明springdoc未生成API文档，需重新排查依赖、扫描规则。

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