开放 API 规范 V2.0 - Enum 类型字段的默认值

Question

我在 Swagger V2.0 中有一个 API 规范的请求正文，如下所示。

"/uri/path":
  ...
  parameters:
    - in: body
      ...
      schema:
        $ref: '#/definitions/StatusObject'

definitions:
  StatusObject:
    status:
      $ref: '#/definitions/StatusEnum'

  StatusEnum:
    type: string
    enum: ['ALPHA', 'BRAVO', 'UNKNOWN']

现在，如果客户端未设置该值，我希望StatusObject.status获得默认值。UNKNOWN我试图按如下方式实现这一目标，但没有运气。

"/uri/path":
  ...
  parameters:
    - in: body
      ...
      schema:
        $ref: '#/definitions/StatusObject'

definitions:
  StatusObject:
    status:
      $ref: '#/definitions/StatusEnum'
      default: 'UNKNOWN'

  StatusEnum:
    type: string
    enum: ['ALPHA', 'BRAVO', 'UNKNOWN']

我也尝试过，'#/definitions/StatusEnum.UNKNOWN'但还是不行。也梳理了文档，但找不到进一步的内容。我缺少什么？

对标记重复的响应

我想要实现的是为此属性设置默认值status。当枚举按如下方式定义时，此方法有效。

"/uri/path":
  ...
  parameters:
    - in: body
      ...
      schema:
        $ref: '#/definitions/StatusObject'

definitions:
  StatusObject:
    status:
      type: string
      enum:
        - 'ALPHA'
        - 'BRAVO'
        - 'UNKNOWN'
      default: 'UNKNOWN'

但是，这对我不起作用，因为我想重用枚举，否则我将不得不在多个地方重复。

Answer 1

由于这只是一种解决方法，并且我不确定是否可以确认这是否是答案，因此我不会将其标记为已接受的答案。这样，我认为对于找到正确方法或更好方法来实现期望的人来说，它仍然是开放的。

显然，问题出在$ref. 众所周知，$refOpenAPI V2.0 中会忽略 的同级。因此，一旦使用$ref就不可能强制执行任何进一步的限制。

对于我的特定用例，由于我想重用枚举定义，因此我使用了V2.0 文档中定义的YAML 锚点。尽管每个 POJO 中都会重复枚举定义，但管理起来并不是那么令人头疼，至少目前是这样。我提出的实现如下。

"/uri/path":
  ...
  parameters:
    - in: body
      ...
      schema:
        $ref: '#/definitions/StatusObject'

definitions:
  StatusObject:
    status:
      enum: *STATUS_ENUM # Referencing the anchor
      default: 'UNKNOWN'

  StatusEnum:
    type: string
    enum: &STATUS_ENUM # This is the anchor
      - 'ALPHA'
      - 'BRAVO'
      - 'UNKNOWN'

还必须注意的是，这种情况下的枚举值不能使用数组语法（即['ALPHA', 'BRAVO', 'UNKNOWN']）定义，因为当您尝试同时使用 YAML 锚点时，它会破坏 YAML 语法规则。