如何创建包含不同类型数组的swagger架构

Question

我正在尝试为包含不同类型的对象数组的对象定义一个swagger模式定义.

这是模板对象(以及所有相关对象类型)的json模式.我知道swagger不支持oneOf谓词,所以我只是想弄清楚如何以骄傲的形式描述这个数据结构.我已经尝试了很多这种语法的变体,但没有一个有效,这是我可以根据规范得到的最接近的一些例子和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

OpenAPI规范3.0将支持oneOf和anyOf.

在2.0中,您可以将具有不同属性的对象定义为type: object(自由格式对象).对于您的情况,您可能希望这样做:

      schema:
        type: array
        items:
          type: object

Answer 2

您可以设置items:对基本类型的引用.特别是在从swagger导出期间,继承模型会因语言而异,但实际上,如果您希望能够接受继承相同基本模型的多个子类,则方法定义会使用基本模型指定可接受的参数类型.

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

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

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

参考

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