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

Question

这是我第一次涉足Swagger,所以请保持温柔.

我有以下定义:

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有一个属性叫做s 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'

当然,这两项工作都没有.原因是当Indicator模型indicator正确描述时,不同的indicators可以具有不同的参数集.

有没有办法基本上定义几个模型的列表,或者可能将模型BBANDS和DEMA模型映射到Indicator？

编辑:在Swagger编辑器中使用@ Helen的第一个建议的结果

Answer 1

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

选项1 - 模型继承

只要您在模型之间有一个共同的字段并且可以用来区分它们,就可以使用模型继承:

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").所以你可以:

• 通过使用继承BBANDS和DEMA模型.IndicatorallOf
• 添加discriminator: type到Indicator表示该type属性将用于区分子模型.
• 定义Payload为数组Indicator.这样它实际上可以是一个数组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

选项2 - 单一模型

如果一切parameters都是整数,你可以有一个单一的模式Indicator与parameters定义为一个HashMap中.但在这种情况下,您将失去parameters为特定指标类型定义精确度的能力.

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

Answer 2

据我所知，数组类型可以保存一种类型，如果您想在一个数组下拥有多种类型，那么需要定义另一个超类型并将子类型包装在其中（可能使用对象类型），如下所示。这个限制是因为 swagger-2.0 不支持 json-schema.org 的所有功能，oneOf，anyOf等allOf是其中的一些功能。

但是您可以使用 swagger-2.0 提供的第三方扩展选项。您可以在其中使用 命名键x-，这意味着您可以包含这些oneOf内容x-oneOf，并且在解析架构时，您可以使用 json-schema 解析器和 swagger 架构解析器来执行此操作。

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

Json模式

{
  "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属性及其构建方式。希望这对您有帮助。