Spring Boot 3.2.4集成Springdoc OpenAPI后Swagger UI无接口定义

针对你使用Spring Boot 3.2.4 + Springdoc OpenAPI 2.0.4遇到的问题，可按以下步骤排查解决：

1. 添加OpenAPI基础配置类 #

Springdoc在Spring Boot 3+环境下，需要显式定义OpenAPI Bean来生成规范。创建一个配置类：

package blossom.reports_service.config;

import io.swagger.v3.oas.models.OpenAPI;
import io.swagger.v3.oas.models.info.Info;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;

@Configuration
public class OpenApiConfig {
    @Bean
    public OpenAPI customOpenAPI() {
        return new OpenAPI()
                .info(new Info()
                        .title("Reports Service API")
                        .version("1.0")
                        .description("Reports Service的API文档"));
    }
}

2. 确认组件扫描范围 #

虽然你提到主应用类在根包，但可显式指定扫描路径确保控制器被识别，在主启动类上添加：

@SpringBootApplication(scanBasePackages = "blossom.reports_service")

3. 调整路径匹配策略 #

Spring Boot 3.2.x默认使用PATH_PATTERN_PARSER，部分情况下会和Springdoc存在兼容问题，在application.properties或application.yml中添加：

spring.mvc.pathmatch.matching-strategy=ant_path_matcher

4. 显式标记API接口 #

在控制器方法上添加@Operation注解，帮助Springdoc识别接口：

import io.swagger.v3.oas.annotations.Operation;

// ... 其他代码

@Operation(summary = "创建挑战摘要", description = "根据用户ID生成并返回挑战摘要")
@PostMapping("/createChallengeSummary/{userId}")
public ChallengeSummary createChallengeSummary(@PathVariable Long userId) {
    return reportsService.createChallengeSummary(userId);
}

5. 检查API规范原始输出 #

访问http://localhost:8080/v3/api-docs，查看返回的JSON数据：

• 如果paths字段为空：说明Springdoc未扫描到控制器，回到步骤2确认扫描范围，或检查是否有拦截器/过滤器阻止了扫描
• 如果paths字段包含你的接口：说明Swagger UI加载异常，可尝试清理浏览器缓存后重新访问

6. 排查依赖冲突 #

确保项目中没有遗留旧版的Springfox等API文档依赖，检查pom.xml中是否有其他可能冲突的依赖并移除。

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