Swagger 2.0: по какой схеме принимать любое (сложное) значение JSON

Question

API, для которого я пишу спецификацию Swagger 2.0, по сути является хранилищем для любого значения JSON.

Я хочу, чтобы путь для чтения значения и путь для хранения любых значений JSON (ноль, число, целое число, строка, объект, массив) с предопределенной глубиной.

К сожалению, кажется, что Swagger 2.0 довольно строг в отношении схем для ввода и вывода и не допускает весь набор схем, разрешенных JSON Schema. Редактор Swagger не допускает, например, смешанные значения (например, свойство, которое может быть либо логическим, либо целочисленным) или свободно определенные массивы (тип элементов должен быть строго определен) и объекты.

Итак, я пытаюсь обойти, определив MixedValue схема:

---
swagger: '2.0'
info:
  version: 0.0.1
  title: Data store API
consumes:
- application/json
produces:
- application/json
paths:
  /attributes/{attrId}/value:
    parameters:
    - name: attrId
      in: path
      type: string
      required: true
    get:
      responses:
        '200':
          description: Successful.
          schema:
            $ref: '#/definitions/MixedValue'
    put:
      parameters:
      - name: value
        in: body
        required: true
        schema:
          $ref: '#/definitions/MixedValue'
      responses:
      responses:
        '201':
          description: Successful.
definitions:
  MixedValue:
    type: object
    properties:
      type:
        type: string
        enum:
        - 'null'
        - boolean
        - number
        - integer
        - string
        - object
        - array
      boolean:
        type: boolean
      number:
        type: number
      integer:
        type: integer
      string:
        type: string
      object:
        description: deep JSON object
        type: object
        additionalProperties: true
      array:
        description: deep JSON array
        type: array
    required:
    - type

Но Swagger Editor отказывается от слабо определенного object а также array свойства.

Вопросы: - Есть ли способ обойти эту проблему? - Это просто ошибка редактора Swagger или сильное ограничение спецификации Swagger 2.0? - Есть ли лучший способ (лучшая практика), чтобы указать, что мне нужно? - Могу ли я ожидать некоторые ограничения в коде, создаваемом swagger для некоторых языков с моей спецификацией API?

Answer 1

Схема произвольного типа может быть определена так:

definitions:
  AnyValue: {}

или если вы хотите description:

definitions:
  AnyValue:
    description: 'Can be anything: string, number, array, object, etc.'

Без определенного type, AnyValue может быть любым - строка, число, логическое значение, массив, объект и т. д. См. этот раздел вопросов и ответов для получения дополнительной информации о том, как typeСхемы работают.

В OpenAPI 3.0 вы можете добавить nullable: true чтобы позволить null значение:

components:
  schemas:
    AnyValue:
      nullable: true
      description: Can be anything, including null.

Вот как Swagger Editor 2.0 обрабатывает параметр тела с помощью AnyValue схема:

Я не знаю, как генераторы кода справляются с этим, хотя.

Answer 2

Может быть, это то, что вы ищете "Узорные объекты":

Шаблон поля: ^ x-

Тип: Любой

Описание: Позволяет расширения схемы Swagger. Имя поля ДОЛЖНО начинаться с x-, например, x-internal-id. Значение может быть нулевым, примитивом, массивом или объектом. Посмотрите Расширения Поставщика для получения дополнительной информации.

Источник: https://github.com/swagger-api/swagger-spec/blob/master/versions/2.0.md