将 OpenAPI 架构枚举值标记为已弃用

Question

是否可以在 OpenAPI 定义中将特定枚举值标记为已弃用？

例如，如何将 Value1 标记为已弃用？

type: string
title: CustomEnum
enum:
  - Value1
  - Value2

Answer 1

如果您使用 OAS 3.0.x，一般答案是否定的，因为它仅限于使用 JSON Schema Draft-04 超集和子集。

如果您使用 OAS 3.1.x，则可以完全使用 JSON Schema，并且

deprecated

是在 JSON Schema 2019-09 中引入的。因此，您可以使用以下内容重构枚举：

在这种情况下，

oneOf

或

anyOf

可以同等替换。

oneOf/anyOf:
  - const: 'red'
  - const: 'green',
    description: green is deprecated, use red or blue
    deprecated: true
  - const: 'blue'

或

oneOf/anyOf:
  - enum:
      - red
      - blue
  - enum:
      - green
        description: this is deprecated
        deprecated: true

如果您使用任何类型的代码生成，其中任何一个都可能是重大更改，因为您不再在此属性的顶层定义枚举。现在它是联合类型，您的代码生成器可能会遇到一些困难。

重要的是要知道

deprecated

关键字只是一个注释并且不会阻止成功验证。 此关键字指示应用程序应避免使用声明的属性。