Swagger:依赖于字段值的变体模式形状

Question

我有一个模型定义为：

Event:
  type: object
  properties:
    id:
      type: string
    timestamp:
      type: string
      format: date-time
    type:
      type: string
      enum:
        - click
        - open
        - sent
    click:
      type: object
      properties:
        url:
          type: string
        title:
          type: string
    open:
      type: object
      properties:
        subject:
          type: string
    sent:
      type: object
      properties:
        subject:
          type: string
        from:
          type: string
        to:
          type: string

但是，根据< code>type枚举字段的值，形状实际上是不同的。它可以是三个中的一个，我试图在< code >示例(见下文)中定义不同之处，但这不起作用。

如您所见，下面显示了三个示例，每个示例都因类型而异。这是 API 的行为方式，但记录此预期行为并不简单。

  examples:
    application/json:
      - id: >
          ad1b12f0-63a8-47b5-9820-3e447143ce7e
        timestamp: >
          2017-09-29T16:45:20.000+00:00
        type: click
        click:
          url: >
            www.some-website-somewhere.org/12345
          title: >
            Click here!
      - id: >
          d9e787fa-db49-4bd8-97c3-df45f159295c
        timestamp: >
          2017-09-29T16:45:20.000+00:00
        type: open
        open:
          subject: >
            Have you seen this?
      - id: >
          30adc194-0f5f-4889-abd4-4fa964d0bb42
        timestamp: >
          2017-09-29T16:45:20.000+00:00
        type: sent
        sent:
          subject: >
            Have you seen this?
          from: >
            [e-mail]
          to: >
            [e-mail]

我读到一些地方提到这是不可能的，但我希望能得到一些“开箱即用”的思想家来帮助我找到解决方案。

Answer 1

这可以使用模型继承/组合和< code >鉴别器来实现。

首先，定义仅包含公共属性的基本模型< code>Event，并将< code>type属性标记为< code>discriminator:

definitions:
  Event:
    type: object
    discriminator: type
    required:
      - type  # discriminator property is required
    properties:
      id:
        type: string
        example: ad1b12f0-63a8-47b5-9820-3e447143ce7e
      timestamp:
        type: string
        format: date-time
        example: 2017-09-29T16:45:20.000+00:00
      type:
        type: string
        enum:
          - click
          - open
          - sent

然后通过< code>allOf从基本< code>Event模型继承点击/打开/发送模型。子模型的名称必须与discriminator属性的值相同。在您的示例中，模型必须命名为< code>click、< code>open和< code>sent。如果您使用Swagger UI，您可以添加< code>title来覆盖显示的模型名称。

  click:
    title: ClickEvent
    allOf:
      - $ref: '#/definitions/Event'
      - type: object
        properties:
          click:
            type: object
            properties:
              url:
                type: string
                example: www.some-website-somewhere.org/12345
              title:
                type: string
                example: Click here!

在操作中，使用基本模型（事件）作为请求或响应架构：

responses:
  200:
    description: OK
    schema:
      $ref: '#/definitions/Event'

客户端应该检查discriminator属性(在本例中为< code>type)的值，以决定使用哪个继承模型。

Swagger UI用户注意:Swagger UI和Swagger编辑器目前不支持基于< code>discriminator切换模型。请关注此问题以获取更新。

在 OpenAPI 3.0 中，它更容易 - 您只需使用 oneOf 为请求或响应定义备用架构即可。

responses:
  '200':
    description: OK
    content:
      application/json:
        schema:
          oneOf:
            - $ref: '#/components/schemas/ClickEvent'
            - $ref: '#/components/schemas/OpenEvent'
            - $ref: '#/components/schemas/SentEvent'
          # Optional mapping of `type` values to models
          discriminator:
            propertyName: type
            mapping:
              click: '#/components/schemas/ClickEvent'
              open:  '#/components/schemas/OpenEvent'
              sent:  '#/components/schemas/SentEvent'