如何在OpenAPI定义中标记特定枚举值为Deprecated？

当然可以在OpenAPI定义里标记特定枚举值为废弃状态，具体实现要分版本来看：

OpenAPI 3.0+（推荐方案） #

从OpenAPI 3.0版本开始，官方支持直接给单个枚举值添加deprecated属性，只需把目标枚举值从字符串形式改成对象形式即可，示例如下：

type: string
title: CustomEnum
enum:
  - value: Value1
    deprecated: true
  - Value2

如果需要给开发者更明确的指引，还可以给废弃的枚举值补充描述信息，说明替代方案：

type: string
title: CustomEnum
enum:
  - value: Value1
    deprecated: true
    description: "此枚举值已废弃，请使用Value2替代"
  - Value2

这种写法会被Swagger UI、Redoc等主流OpenAPI工具识别，废弃的枚举值会显示为划掉的样式，直观告知开发者该值不再推荐使用。

OpenAPI 2.0（Swagger 2.0） #

OpenAPI 2.0版本没有官方支持的单个枚举值废弃标记，只能通过枚举的整体描述字段来标注：

type: string
title: CustomEnum
enum:
  - Value1
  - Value2
description: "注意：Value1已废弃，请优先使用Value2"

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