springdoc-openapi调用时URL路径参数未替换问题求助

DevOps 小满

2026-8-19

解决springdoc-openapi路径参数未正确替换的问题

你的问题出在@Parameter注解的name属性配置错误：路径占位符是{id}，但你给@Parameter指定的name是"ID of client"，springdoc无法把这个参数和路径里的{id}关联起来，所以生成curl命令时不会替换占位符。

修复方案

把@Parameter的name改成和路径参数一致的"id"，或者直接省略name属性（因为@PathVariable已经明确了参数名，springdoc会自动识别）：

修改后的代码示例：

@Operation(summary = "Gets a client.")
@ApiResponses({ @ApiResponse(responseCode = "200", description = "Ok"),
                @ApiResponse(responseCode = "404", description = "Not found") })
@GetMapping(path = "/{id}")
public ResponseEntity get(@PathVariable @Parameter(name = "id", description = "ID of client") final Long id) {
    final ClientDTO response = clientService.get(id);

    return ResponseEntity.ok(response);
}

或者更简洁的写法（省略name，仅保留描述说明）：

@Operation(summary = "Gets a client.")
@ApiResponses({ @ApiResponse(responseCode = "200", description = "Ok"),
                @ApiResponse(responseCode = "404", description = "Not found") })
@GetMapping(path = "/{id}")
public ResponseEntity get(@PathVariable @Parameter(description = "ID of client") final Long id) {
    final ClientDTO response = clientService.get(id);

    return ResponseEntity.ok(response);
}