Как вы создаете схему swagger, которая включает в себя множество различных типов

Я пытаюсь определить определение схемы 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'

Ответ 1

OpenAPI Specification 3.0 поддерживает oneOf и anyOf.

В 2.0 вы можете определить объект с различными свойствами как только type: object (объект свободной формы). Для вашего случая вы можете сделать это:

      schema:
        type: array
        items:
          type: object

Ответ 2

Вы можете установить ссылку items: на базовый тип. Модель наследования будет варьироваться в зависимости от языка во время экспорта от чванства, но на практике определения методов определяют приемлемые типы параметров, используя базовую модель, если вы хотите иметь возможность принимать несколько подклассов, которые наследуют одну и ту же базовую модель.

Фрагмент 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);

Ответ 3

Пример ответа API, который возвращает массив видео

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

Ссылка

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