能否在Swagger 2.0/3.0中标记枚举值为已废弃？

好问题！这确实是API维护中非常常见的场景——既要兼容旧枚举值的反序列化需求，又要清晰告知使用者哪些值已经废弃。下面针对Swagger 2.0和3.0+版本分别给出可行方案：

Swagger 2.0 解决方案 #

Swagger 2.0本身没有原生支持枚举值的废弃标记，但它允许通过自定义扩展字段（以x-开头的属性）来实现这个需求，同时完全保留废弃枚举值用于反序列化。

两种常用实现方式 #

1. 全局枚举扩展+描述说明
   在定义枚举的definitions中添加自定义扩展字段标记废弃值，同时在描述里明确说明：

   swagger: '2.0'
   info:
     title: 订单API
     version: 1.0.0
   paths: {}
   definitions:
     OrderStatus:
       type: string
       enum:
         - PENDING
         - SHIPPED
         - CANCELLED
         - REFUNDED  # 需保留用于反序列化的废弃值
       description: |
         订单状态枚举：
         - PENDING: 待处理
         - SHIPPED: 已发货
         - CANCELLED: 已取消
         - *REFUNDED*: 已废弃，请使用CANCELLED替代
       x-deprecated-enums: ["REFUNDED"]
   

2. 精细化枚举项扩展
   如果需要给每个枚举项单独添加描述和废弃标记，可以用自定义结构来定义枚举值细节：

   definitions:
     OrderStatus:
       type: string
       enum: [PENDING, SHIPPED, CANCELLED, REFUNDED]
       x-enum-details:
         - value: PENDING
           description: 待处理订单
         - value: SHIPPED
           description: 已发货订单
         - value: CANCELLED
           description: 已取消订单
         - value: REFUNDED
           description: 已废弃状态，请使用CANCELLED替代
           x-deprecated: true
   

代码生成适配 #

你们使用的Java类型生成器（比如OpenAPI Generator）可以通过自定义模板或者配置来识别这些x-开头的废弃标记，自动给对应的Java枚举项添加@Deprecated注解，既保留枚举值用于反序列化，又能在代码层面标记废弃。

Swagger 3.0+（OpenAPI 3.0/3.1）解决方案 #

Swagger 3.0对应OpenAPI 3.0规范，这一版本依然没有原生的枚举废弃属性，但同样可以沿用上述自定义扩展的方式。

而OpenAPI 3.1（Swagger 3.1）则原生支持枚举值的废弃标记，无需依赖自定义扩展：

openapi: 3.1.0
info:
  title: 订单API
  version: 1.0.0
paths: {}
components:
  schemas:
    OrderStatus:
      type: string
      enum:
        - value: PENDING
          description: 待处理订单
        - value: SHIPPED
          description: 已发货订单
        - value: CANCELLED
          description: 已取消订单
        - value: REFUNDED
          description: 已废弃状态，请使用CANCELLED替代
          deprecated: true

这种写法下，Swagger UI等工具会自动将REFUNDED标记为废弃（通常会显示为灰色或带删除线），主流的Java代码生成器也能直接识别deprecated属性，生成带有@Deprecated注解的枚举项，完美兼容反序列化需求。

关键注意点 #

• 无论使用哪个版本的Swagger，不要从enum列表中移除废弃值，这样才能保证旧数据的反序列化正常工作；
• 一定要在枚举的描述中清晰标注废弃值的替代方案，避免使用者误用。

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