在 Swagger 2.0 中定义多个模型的数组 [英] Define array of multiple models in Swagger 2.0

问题描述

这是我第一次接触 Swagger，所以请保持温和.

This is my first foray into Swagger so please be gentle.

我有以下定义:

definitions:
  Payload:
    type: object
    properties:
      indicators:
        type: array
        items:
          $ref: '#/definitions/Indicator'
  Indicator:
    type: object
    properties:
      type:
        type: string
      computeOn:
        type: array
        items:
          type: string
        default:
          - close
      parameters:
        type: object
  BBANDS:
    properties:
      type:
        type: string
        default: BBANDS
      computeOn:
        type: array
        items:
          type: string
        default:
          - close
      parameters:
        type: object
        properties:
          timeperiod:
            type: integer
            format: int32
            default: 5
          nbdevup:
            type: integer
            format: int32
            default: 2
          nbdevdn:
            type: integer
            format: int32
            default: 2
          matype:
            type: integer
            format: int32
            default: 0
  DEMA:
    properties:
      type:
        type: string
        default: DEMA
      computeOn:
        type: array
        items:
          type: string
        default:
          - close
      parameters:
        type: object
        properties:
          timeperiod:
            type: integer
            format: int32
            default: 5

所以 Payload 有一个名为 indicator 的属性，它是一个 Indicator 数组.BBANDS 和 DEMA 是 type Indicator 的模型(我知道这不会转换为 Swagger).我想要做的是定义一个实际模型数组及其默认值，在本例中为 BBANDS 和 DEMA.像这样:

So Payload has a property called indicator which is an array of Indicators. The BBANDS and DEMA are models which are of type Indicator (which I know doesn't translate to Swagger). What I'd like to do is define an array of the actual models with their defaults, in this case BBANDS and DEMA. Something like this:

definitions:
  Payload:
    type: object
    properties:
      indicators:
        type: array
        items:
          - '#/definitions/BBANDS'
          - '#/definitions/DEMA'

或

definitions:
  Payload:
    type: object
    properties:
      indicators:
        type: array
        items:
          - $ref '#/definitions/BBANDS'
          - $ref '#/definitions/DEMA'

当然这两者都不起作用.原因是虽然 Indicator 模型正确地描述了 indicator，但不同的 indicator 可以有不同的参数集.

Neither of which work of course. The reason is while the Indicator model describes an indicator correctly, different indicators can have a different parameter set.

有没有办法从本质上定义多个模型的列表，或者将 BBANDS 和 DEMA 模型映射到 Indicator 中?

Is there a way to essentially define a list of several models or perhaps map the BBANDS and DEMA models into Indicator?

推荐答案

Swagger/OpenAPI 2.0 不支持 items 的多种类型，但有几种方法可以描述您的需求.

Swagger/OpenAPI 2.0 does not support multiple types for items, but there are a couple of ways to describe what you need.

只要有一个字段是模型之间通用的，可以用来区分它们，就可以使用模型继承:

As long as you have one field that is common between the models and can be used to distinguish between them, you can use model inheritance:

https://github.com/OAI/OpenAPI-Specification/blob/master/versions/2.0.md#schemaDiscriminatorhttps://github.com/OAI/OpenAPI-Specification/blob/master/versions/2.0.md#composition-and-inheritance-polymorphism

在您的示例中，此属性是 type(type="BBANDS" 或 type="DEMA").所以你可以:

In your example, this property is type (type="BBANDS" or type="DEMA"). So you can:

• 使用 allOf 从 Indicator 继承 BBANDS 和 DEMA 模型.
• 将discriminator: type 添加到Indicator 以指示type 属性将用于区分子模型.
• 将Payload 定义为Indicator 的数组.这样它实际上可以是一个 BBANDS 数组或一个 DEMA 数组.

• Inherit the BBANDS and DEMA models from Indicator by using allOf.
• Add discriminator: type to Indicator to indicate that the type property will be used to distinguish between the sub-models.
• Define Payload as an array of Indicator. This way it can actually be an array of BBANDS or an array of DEMA.

definitions:
  Payload:
    type: object
    properties:
      indicators:
        type: array
        items:
          $ref: '#/definitions/Indicator'

  Indicator:
    type: object
    properties:
      type:
        type: string
        # Limit the possible values if needed
        #enum:
        #  - BBANDS
        #  - DEMA
      computeOn:
        type: array
        items:
          type: string
        default:
          - close

    # The "type" property will be used to distinguish between the sub-models.
    # The value of the "type" property MUST be the schema name, that is, "BBANDS" or "DEMA".
    # (Or in other words, the sub-model schema names must match possible values of "type".)
    discriminator: type
    required:
      - type

  BBANDS:
    allOf:
      - $ref: '#/definitions/Indicator'
      - type: object
        properties:
          parameters:
            type: object
            properties:
              timeperiod:
                type: integer
                format: int32
                default: 5
              nbdevup:
                type: integer
                format: int32
                default: 2
              nbdevdn:
                type: integer
                format: int32
                default: 2
              matype:
                type: integer
                format: int32
                default: 0
  DEMA:
    allOf:
      - $ref: '#/definitions/Indicator'
      - type: object
        properties:
          parameters:
            type: object
            properties:
              timeperiod:
                type: integer
                format: int32
                default: 5

选项 2 - 单一模型

如果所有参数都是整数，你可以有一个单一的模型Indicator，其中parameters定义为一个hashmap.但在这种情况下，您将无法为特定指标类型定义确切的参数.

Option 2 - Single Model

If all parameters are integer, you can have a single model Indicator with parameters defined as a hashmap. But in this case you lose the ability to define the exact parameters for specific indicator types.

definitions:
  Indicator:
    type: object
    properties:
      type:
        type: string
        enum:
          - BBANDS
          - DEMA
      computeOn:
        type: array
        items:
          type: string
        default:
          - close
      parameters:
        type: object
        properties:
          # This is a common parameter in both BBANDS and DEMA
          timeperiod:
            type: integer
            format: int32
            default: 5
        # This will match additional parameters "nbdevup", "nbdevdn", "matype" in BBANDS
        additionalProperties:
          type: integer

这篇关于在 Swagger 2.0 中定义多个模型的数组的文章就介绍到这了，希望我们推荐的答案对大家有所帮助，也希望大家多多支持IT屋！