如何在Swagger中标记@PathVariable为Deprecated并兼容接口请求？

核心思路 #

通过兼容新旧两个请求路径，分别处理旧路径的废弃参数和新路径的参数，同时让Swagger正确标记旧路径及参数为废弃状态，彻底避免请求报错问题。

具体实现步骤 #

1. 拆分新旧接口方法
   创建两个独立方法分别对应旧路径和新路径，旧方法标记为废弃，内部复用新方法的业务逻辑，保证新旧请求都能正常处理：

// 旧接口：标记为废弃，处理原三参数路径变量
@Deprecated
@GetMapping(value = "/aaa/bbb/{x_y_z}", produces = "application/json")
public ResponseEntity<YourResponse> deprecatedMethod(
        @Parameter(description = "x_y_z - x是第一个ID，y是第二个ID，z是第三个ID（已废弃）", required = true, deprecated = true)
        @PathVariable String x_y_z) {
    // 解析旧参数为新参数格式，复用新接口逻辑
    String[] idParts = x_y_z.split("_");
    String x_y = idParts[0] + "_" + idParts[1]; // 忽略原z参数
    return newMethod(x_y);
}

// 新接口：处理新两参数路径变量
@GetMapping(value = "/aaa/bbb/{x_y}", produces = "application/json")
public ResponseEntity<YourResponse> newMethod(
        @Parameter(description = "x_y - x是第一个ID，y是第二个ID", required = true)
        @PathVariable String x_y) {
    // 核心业务逻辑实现
    YourResponse response = // 编写业务处理代码
    return ResponseEntity.ok(response);
}

2. Swagger废弃标记说明

• 旧方法上的@Deprecated会让Swagger将整个旧接口标记为废弃状态（通常显示为灰色或带删除线）。
• 旧参数上的@Parameter(deprecated = true)会在Swagger文档中明确标记该路径参数为废弃，提示使用者切换新参数。

3. 避免参数冲突的关键
   不要在同一个方法中同时声明两个路径变量，否则Spring MVC会因为路径无法同时匹配两个变量而抛出500/400错误。拆分方法后，每个方法对应唯一的路径变量，请求可正常路由。

替代方案（单方法兼容） #

如果希望用单个方法处理，可以通过@RequestMapping的路径数组同时支持新旧路径，再通过参数的required=false区分，但需手动处理参数存在性：

@GetMapping(value = {"/aaa/bbb/{x_y_z}", "/aaa/bbb/{x_y}"}, produces = "application/json")
public ResponseEntity<YourResponse> unifiedMethod(
        @Parameter(description = "x_y_z - x是第一个ID，y是第二个ID，z是第三个ID（已废弃）", required = false, deprecated = true)
        @Deprecated
        @PathVariable(required = false) String x_y_z,
        
        @Parameter(description = "x_y - x是第一个ID，y是第二个ID", required = false)
        @PathVariable(required = false) String x_y) {
    // 确定有效参数
    String targetParam;
    if (x_y != null) {
        targetParam = x_y;
    } else if (x_y_z != null) {
        String[] parts = x_y_z.split("_");
        targetParam = parts[0] + "_" + parts[1];
    } else {
        throw new IllegalArgumentException("必须提供有效路径参数");
    }
    
    // 核心业务逻辑实现
    YourResponse response = // 编写业务处理代码
    return ResponseEntity.ok(response);
}

注意：单方法方案需要严格处理参数非空判断，避免出现参数缺失的情况，同时Swagger会显示两个路径参数，其中旧参数标记为废弃。

内容的提问来源于stack exchange，提问作者Rachan R K