Добавление примера на основе схемы

Question

Скажем, у меня есть схема, которая описывает значение, возвращаемое вызовом API. Схема содержит сложные объекты, которые имеют свою собственную схему, например: объект под названием «интерфейсы». Есть ли способ заставить swagger UI сгенерировать пример для поля 'interfaces' на основе схемы интерфейса?

interfaces:
  description: A list of the device's interfaces
  type: array
  items:
    type: object
    required: true
    schema: 
      $ref: '#components/schemas/Interface'
    example: #<---- What should I put here?
  required: true

Interface:
  type: object
  properties:
    name:
      description: Interface's name
      type: string
      required: true
      example: eth0
    IP:
     ...

Answer 1

После тщательного прочтения документации выясняется, что OpenAPI 3.0 поддерживает определение общих примеров, которые можно повторно использовать в файлах yaml документации API.См. Пример в разделе «Повторное использование примеров» в следующей ссылке .

Answer 2

В примере вы должны указать ожидаемое значение примитивной переменной или объекта. Скажем, если тип переменной USERNAME - строка, примером может быть «exampleuser190». Если ID имеет целочисленный тип, то пример может быть «845» или что-то подобное. Вам нужно добавить пример, но постарайтесь быть точным, чтобы представить реальную ситуацию и структуру переменных в API.

Итак, не используйте простой пример в качестве "5", если ожидаемое значение имеет длину 12 цифр, с двумя нулями впереди, например, это "003454534546" или какой-то сложный ключ для имен пользователей и т. Д.

В вашем случае я бы поместил пример в схему интерфейса или пример ожидаемого объекта (как он выглядит):

interfaces:
  description: A list of the device's interfaces
  type: array
  items:
    type: object
    required: true
    schema: 
      $ref: '#components/schemas/Interface'
  required: true

components:
  schemas:
   Interface:
     variableXX:
       type: integer
       example: 34534