Как определить типы исключения для элементов массива с помощью OpenAPI / Swagger?

Question

Документация Swagger объясняет, как определять массивы, содержащие смешанные типы , такие как ["foo", 5, -2, "bar"]. Но как определить, что массив должен содержать или одного типа элементов (строки, ["foo", "bar"]) или другого (целые числа, [5, -2])?

Я пробовал это, но Swagger UI не может отрендерить его, поэтому я думаю, что это неправильно:

      oneOf:
        - items:
          - $ref: '#/components/schemas/SchemaA'
        - items:
          - $ref: '#/components/schemas/SchemaB'

Answer 1

Прежде всего, помните, что oneOf поддерживается только в OpenAPI 3.0 (openapi: 3.0.0), но не в OpenAPI 2.0 (swagger: '2.0').

Ваш сценарий может быть определен с помощью oneOf, например, так:

oneOf:
  - type: array
    items:
      type: string
  - type: array
    items:
      type: integer
  - type: array
    items:
      $ref: '#/components/schemas/SchemaA'

В ванильной JSON-схеме type: array можно переместить из oneOf и поместить рядом с oneOf, но я не уверен, позволяет ли OpenAPI это (спецификация OpenAPI неясна для этого).

type: array
oneOf:
  - items:
      type: string
  - items:
      type: integer
  - items:
      $ref: '#/components/schemas/SchemaA'

Я пробовал это, но Swagger UI не может сделать это

В настоящее время Swagger UI не генерирует автоматически примеры для oneOf и anyOf схем (см. эту проблему ). Обходной путь должен добавить example вместе с oneOf вручную:

example: [1, 2, 3]  # <------
oneOf:
  - type: array
    items:
      type: string
  - type: array
    items:
      type: integer
  - type: array
    items:
      $ref: '#/components/schemas/SchemaA'