Spring Boot中如何用Swagger注解为废弃接口关联新版本接口？

AI 小北

2026-8-22

解决Spring Boot微服务Swagger标记废弃接口并关联v2版本的方案

核心思路

仅用@Deprecated注解只能标记接口废弃，但要在Swagger UI里显示关联的v2接口链接，需要结合Swagger专属注解配置描述信息和废弃状态。

针对OpenAPI 3.x（SpringDoc 常用版本）

如果你的项目用的是SpringDoc（适配OpenAPI 3.x），直接在v1接口的@Operation注解里配置：

设置deprecated = true，让接口归入废弃区域
在description里通过Markdown格式添加v2接口的链接（Swagger UI支持解析Markdown）

代码示例：

@Deprecated
@GetMapping("/endpoint/v1")
@Operation(
    deprecated = true,
    description = "该接口已废弃，请使用新版本接口：[/endpoint/v2](/endpoint/v2)"
)
public ResponseEntity<String> oldEndpoint() {
    // 业务逻辑
    return ResponseEntity.ok("v1 response");
}

// v2接口示例
@GetMapping("/endpoint/v2")
@Operation(summary = "新版本接口")
public ResponseEntity<String> newEndpoint() {
    return ResponseEntity.ok("v2 response");
}

针对Swagger 2.x（Springfox 旧版本）

如果用的是Springfox（Swagger 2.x），在@ApiOperation里配置废弃状态和描述：

@Deprecated
@GetMapping("/endpoint/v1")
@ApiOperation(
    value = "旧版本接口",
    notes = "该接口已废弃，请使用新版本接口：[/endpoint/v2](/endpoint/v2)",
    deprecated = true
)
public ResponseEntity<String> oldEndpoint() {
    return ResponseEntity.ok("v1 response");
}