如何创建一个包含不同类型数组的swagger模式

Question

我试图为一个包含不同类型对象数组的对象定义一个swagger模式定义。

下面是模板对象（以及所有相关对象类型）的 json 架构。我知道 swagger 不支持 oneOf 谓词，所以我只是想弄清楚如何在 swagger 中描述这个数据结构。我已经尝试了这种语法的许多变体，但没有一个有效，这是我根据规范和这里找到的一些例子所能达到的最接近的：http://json-schema.org/example2.html

swagger: '2.0'
info:
  version: 1.0.0
  title: IDMU
paths:

definitions:
  template:
    type: object
    properties:
      collection:
        type: string
      name:
        type: string
      columnValue:
        type: string
      description:
        type: string
      outputFile:
        type: string
      content:
        type: string
      directives:
        type: array
        items:
          type: object
          oneOf: 
            - 
              $ref: '#/definitions/directiveRequire'
            - 
              $ref: '#/definitions/directiveReplace'
            - 
              $ref: '#/definitions/directiveReplaceRowSql'
            - 
              $ref: '#/definitions/directiveReplaceRowCsv'
            - 
              $ref: '#/definitions/directiveReplaceColSql'
            - 
              $ref: '#/definitions/directiveReplaceColCsv'
            - 
              $ref: '#/definitions/directiveInsertTag'
            - 
              $ref: '#/definitions/directiveInsertCsv'
            - 
              $ref: '#/definitions/directiveInsertSql'
  providerCsv:
    type: object
    properties:
      type:
        type: integer
        maximum: 3
        minimum: 3
      tag:
        type: string
      url:
        type: string
      staticData:
        type: string
  providerTag:
    type: object
    properties:
      type:
        type: integer
        maximum: 2
        minimum: 2
      tag:
        type: string
      condition:
        type: integer
      list:
        type: boolean
      value:
        type: string
  providerSql:
    type: object
    properties:
      type:
        type: integer
        maximum: 1
        minimum: 1
      source:
        type: string
      columns:
        type: string
      from:
        type: string
      where:
        type: string
  directive:
    type: object
    discriminator: type
    properties:
      type:
        type: integer
      softFail:
        type: boolean
    required:
      - type
  directiveRequire:
    type: object
    allOf:
      - $ref: '#/definitions/directive'
      - properties:
          tags:
            type: array
            items:
              type: string
  directiveReplace:
    type: object
    allOf:
      - $ref: '#/definitions/directive'
      - properties:
          description:
            type: string
          from:
            type: string
          to:
            type: string
  directiveReplaceRowSql:
    type: object
    allOf:
      - $ref: '#/definitions/directive'
      - properties:
          description:
            type: string
          provider:
            $ref: '#/definitions/providerSql'
  directiveReplaceRowCsv:
    type: object
    allOf:
      - $ref: '#/definitions/directive'
      - properties:
          description:
            type: string
          provider:
            $ref: '#/definitions/providerCsv'
  directiveReplaceColCsv:
    type: object
    allOf:
      - $ref: '#/definitions/directive'
      - properties:
          description:
            type: string
          fromColumn:
            type: string
          toColumn:
            type: string
          provider:
            $ref: '#/definitions/providerCsv'
  directiveReplaceColSql:
    type: object
    allOf:
      - $ref: '#/definitions/directive'
      - properties:
          description:
            type: string
          fromColumn:
            type: string
          toColumn:
            type: string
          provider:
            $ref: '#/definitions/providerSql'
  directiveInsertTag:
    type: object
    allOf:
      - $ref: '#/definitions/directive'
      - properties:
          description:
            type: string
          notLast:
            type: array
            items:
              type: string
          onlyLast:
            type: array
            items:
              type: string
          provider:
            $ref: '#/definitions/providerTag'
      directiveInsertSql:
        type: object
        allOf:
          - $ref: '#/definitions/directive'
          - properties:
              description:
                type: string
              notLast:
                type: array
                items:
                  type: string
              onlyLast:
                type: array
                items:
                  type: string
              provider:
                $ref: '#/definitions/providerSql'
      directiveInsertCsv:
        type: object
        allOf:
          - $ref: '#/definitions/directive'
          - properties:
              description:
                type: string
              notLast:
                type: array
                items:
                  type: string
              onlyLast:
                type: array
                items:
                  type: string
              provider:
                $ref: '#/definitions/providerCsv'

Answer 1

返回视频数组的示例API响应

  responses:
    '200':
      description: An array of videos
      schema:
        type: array
        items:
          $ref: '#/definitions/Video' 

参考

https://swagger.io/docs/specification/adding-examples/

Answer 2

您可以设置项目：对基类型的引用。在从 swagger 导出期间，继承模型将因语言而异，但在实践中，如果您希望能够接受继承同一基模型的多个子类，则方法定义将使用基模型指定可接受的参数类型。

招摇片段-

definitions:
  template:
    type: object
    properties:
      collection:
        type: string
      ...
      directives:
        type: array
        items:
          $ref: '#/definitions/directive'
  directive:
    type: object
    discriminator: type
    properties:
      type:
        type: integer
      softFail:
        type: boolean
    required:
      - type
  directiveRequire:
    allOf:
    - $ref: '#/definitions/directive'
    - type: object
      properties:
        tags:
          type: array
          items:
            type: string
  directiveReplace:
    allOf:
    - $ref: '#/definitions/directive'
    - type: object
      properties:
        description:
          type: string
        from:
          type: string
        to:
          type: string

伪代码-

class template {
  // all the other properties
  directive[] directives;
  function addDirective(directive newDirective) {
    this.directives.push(newDirective);
  }
}

class directive {
  int type;
  boolean softFail;
}

class directiveRequire inherits directive {
 //inherits type, softFail
 string[] tags;
}

class directiveReplace {
  //inherits type, softFail
  string description;
  string from;
  string to;
}

template templateOne = new template();

directiveReplace directiveOne = new directiveReplace();
directiveOne.type = "replace";
directiveOne.softFail = false;
directiveOne.description = "first directive replace";
directiveOne.from = "first";
directiveOne.to = "one";

directiveRequire directiveTwo = new directiveRequire();
directiveTwo.type = "require";
directiveTwo.softFail = true;
directiveTwo.tags = ["second","directive"];

templateOne.addDirective(directiveOne);
templateOne.addDirective(directiveTwo);

Answer 3

OpenAPI 3.0 支持 oneOf 和 anyOf：

      schema:
        type: array
        items:
          oneOf:
            - $ref: '#/components/schemas/directiveRequire'
            - $ref: '#/components/schemas/directiveReplace'
            - ...

在OpenAPI 2.0中，您可以将具有不同属性的对象定义为< code>type: object(自由形式的对象)。对于您的情况，您可能需要这样做:

      schema:
        type: array
        items:
          type: object