spring-boot - Open API Spec V2.0 - 枚举类型字段的默认值

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 上。众所周知，$ref 的兄弟在 OpenAPI V2.0 中被忽略了。因此，一旦您使用 $ref 就无法实现任何进一步的限制。

对于我的特定用例，因为我想重用我的枚举定义，所以我使用了 YAML Anchors如 V2.0 文档中所定义。尽管在每个 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 anchor 时，YAML 语法规则。