在Swagger 2.0中定义多个模型的数组

Question

这是我第一次涉足斯威格，所以请温柔点。

我有以下定义：

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是indicator类型的模型（我知道这不会转化为招摇）。我想做的是定义一个带有默认值的实际模型数组，在本例中是BBANDS和DEMA。大概是这样的：

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'

当然，两者都不起作用。原因是，虽然Signator模型正确地描述了指标，但不同的指标可以具有不同的参数集。

有没有一种方法可以从本质上定义几个模型的列表，或者将BBANDS和DEMA模型映射到指标中？




Answer 1

数组类型中的AFAIK可以保存一个类型，如果您希望在一个数组下有多个类型，则需要定义另一个超级类型并将子类型包装在其中（可能使用对象类型），如下面所示。这是因为swagger-2.0不支持json模式的所有功能。org、oneOf、anyOf、allOf等都是其中的一部分。

但是您可以使用swagger-2.0提供的第三方扩展选项。其中，您可以使用x-命名键，这意味着您可以像x-oneOf一样包含这些oneOf，在解析模式时，您可以使用json模式解析器和swagger模式解析器来完成。

下面给出了一个这样的例子，

Json模式

json prettyprint-override">{
  "id": "http://some.site.somewhere/entry-schema#",
  "$schema": "http://json-schema.org/draft-04/schema#",
  "description": "schema for an fstab entry",
  "type": "object",
  "required": [
    "storage"
  ],
  "properties": {
    "storage": {
      "type": "object",
      "oneOf": [
        {
          "$ref": "#/definitions/diskDevice"
        }
      ]
    },
    "deviceList": {
      "type": "array",
      "minItems": 1,
      "items": {
        "$ref": "#/definitions/Device"
      }
    }
  },
  "definitions": {
    "diskDevice": {
      "type": "object",
      "properties": {
        "label": {
          "type": "string"
        }
      },
      "required": [
        "label"
      ]
    },
    "blockDevice": {
      "type": "object",
      "properties": {
        "blockId": {
          "type": "number"
        }
      },
      "required": [
        "blockId"
      ]
    },
    "CharDevice": {
      "type": "object",
      "properties": {
        "charDeviceName": {
          "type": "string"
        }
      },
      "required": [
        "charDeviceName"
      ]
    },
    "Device": {
      "type": "object",
      "oneOf": [
        {
          "$ref": "#/definitions/diskDevice"
        },
        {
          "$ref": "#/definitions/blockDevice"
        },
        {
          "$ref": "#/definitions/CharDevice"
        }
      ]
    }
  }
}

数据或有效载荷

{
"storage": {"label": "adsf"},
"deviceList": [{"label": "asdf"}, {"blockId": 23}, {"charDeviceName": "asdf"}]
}

使用这个网站来玩你的样本数据-http://www.jsonschemavalidator.net/

请注意deviceList属性及其构造方式。希望这对你有帮助。

Answer 2

匿名用户

Swagger/OpenAPI 2.0不支持项的多种类型，但是有几种方法可以描述您需要的内容。

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

https://github.com/OAI/OpenAPI-Specification/blob/master/versions/2.0.md#schemaDiscriminator https://github.com/OAI/OpenAPI-Specification/blob/master/versions/2.0.md#composition-遗传多态性

在您的示例中，此属性是type（type="BBANDS"或type="DEMA"）。所以你可以：

• 通过使用allOf继承BBANDS和DEMA模型。
• 添加鉴别器：类型到指示符，以指示将使用类型属性来区分子模型。
• 定义Payload作为一个数组的Signator。这样，它实际上可以是一个BBANDS数组或一个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

如果所有参数都是整数，则可以使用定义为hashmap的参数的单个模型Signator。但是在这种情况下，您将失去为特定指标类型定义确切的参数的能力。

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