从Swagger迁移至Springdoc OpenAPI后Swagger UI显示无操作定义错误

问题分析及修复方案 #

1. 控制器方法缺失HTTP请求注解 #

你的端点代码仅添加了Springdoc的@Operation等注解，但未标注HTTP请求方法（如@GetMapping、@PostMapping），导致Springdoc无法识别这是一个可暴露的API接口。

修复示例：

@GetMapping("/api/{id}") // 补充HTTP请求注解
@Operation(summary = "Test API", description = "This is a test api")
@ApiResponses(value = {
    @ApiResponse(responseCode = "200", description = "Success"),
    @ApiResponse(responseCode = "400", description = "ID is invalid")})
public @ResponseBody ResponseEntity<Resource> getId(
    @Parameter(description = "ID描述", required = true) @PathVariable final String id) {
    //Implementation
}

注意：@Parameter中的IdDesc若为未定义变量，需替换为具体描述字符串或确保该常量已正确定义。

2. GroupedOpenApi路径匹配规则错误 #

你配置的pathsToMatch("/api.*")不符合Springdoc默认的Ant路径匹配规则，若要匹配所有以/api开头的路径，需改为"/api/**"。

修复配置类：

@Bean
public GroupedOpenApi api() {
  return GroupedOpenApi.builder().group("Test")
    .packagesToScan("com.test") // 确保控制器类在该包或其子包下
    .pathsToMatch("/api/**").build(); // 修改路径匹配规则
}

3. 确认控制器包扫描范围 #

检查你的控制器类是否在com.test包或其子包下，否则packagesToScan("com.test")无法扫描到控制器，导致接口不被识别。

4. 核对Springdoc依赖版本 #

• Spring Boot 3.x需搭配Springdoc v2.x版本
• Spring Boot 2.x需搭配Springdoc v1.x版本

可在POM中明确指定版本（以Spring Boot 3.x为例）：

<dependency>
  <groupId>org.springdoc</groupId>
  <artifactId>springdoc-openapi-starter-webmvc-ui</artifactId>
  <version>2.2.0</version> <!-- 指定适配版本 -->
</dependency>

5. 验证OpenAPI规范生成结果 #

直接访问/v3/api-docs/Test（对应你定义的group名称），若返回的JSON中无paths字段，说明接口未被识别，需重新检查上述步骤。

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