SpringDoc Swagger报“No operations defined in spec!”问题排查求助

DevOps 小满

2026-6-23

问题排查与解决方法

针对你遇到的Swagger提示"No operations defined in spec!"的问题，主要有以下几个关键问题需要修复：

1. 路径匹配配置错误

你的application.properties中springdoc.pathsToMatch配置的是/vtm/v1，但控制器的根路径是/api/v1/orders，两者完全不匹配，导致springdoc无法扫描到你的接口。

修复方式：
修改application.properties中的路径匹配配置，改为匹配控制器的路径：

springdoc.pathsToMatch=/api/v1/**

2. Get请求的参数注解错误

你的getOrderDetails方法使用了@GetMapping("/orders/{orderId}")路径变量，但参数上用了@RequestParam("orderId")，这是错误的用法，路径变量应该用@PathVariable。虽然这个不会直接导致Swagger扫描不到接口，但会导致接口无法正常调用，建议一并修复：

修复后的代码：

@Operation(summary = "Find Orders by ID", description = "Get order details by order ID", tags = { "contact" })
@GetMapping(value = "/orders/{orderId}", produces = { "application/json", "application/xml" })
public Order getOrderDetails(@PathVariable("orderId") int orderId) {
    Order order = new Order();
    return order;
}

3. 部分接口缺少Swagger注解（可选优化）

虽然springdoc可以自动扫描无Swagger注解的接口，但为了确保接口能被正确识别并生成更清晰的文档，建议给所有接口方法添加@Operation注解，比如Post、Put、Delete方法：

示例（Post方法添加注解）：

@Operation(summary = "Save Order", description = "Create a new order record", tags = { "contact" })
@PostMapping("/orders")
public int saveOrderDetails(@RequestBody Order order) {
    int orderId = 1;
    return orderId;
}