openapi: ссылка на существующий пример в списке

Question

У меня есть спецификация OpenAPI 3.0.0 с компонентом Widget, который включает в себя раздел example:

components:
  schemas:
    Widget:
      properties:
        id:
          type: string
        description:
          type: string
        cost:
          type: float
      example:
        id: 1234
        description: An example widget
        cost: 0.10

Я добавляю компонент Warehouse, который включает в себя список Widgets.Есть ли способ использовать example в схеме Widget в схеме Warehouse?Что-то вроде:

    Warehouse:
      properties:
        id:
          type: string
        location:
          type: string
        widgets:
          type: array
          items:
            $ref: '#/components/schemas/Widget'
      example:
        id: 4321
        widgets:
          - $ref: '#/components/schemas/Widget'

Выше не сработало.Я смотрел на перемещение example из схемы Widget в #/components/examples/WidgetExample, но я все еще не был уверен, как будет выглядеть синтаксис для обозначения этого.

Answer 1

Ключевое слово example не поддерживает $ref.

. Вместо этого вы можете изменить схему Warehouse, чтобы использовать примеры на уровне свойств для свойств, отличных от widgets, в данном случаепример для widgets будет «унаследован» от схемы Widget.По крайней мере, именно так это работает в Swagger UI и Swagger Editor.

    Warehouse:
      properties:
        id:
          type: string
          example: 4321   # <----
        location:
          type: string
          example: Sample location   # <----
        widgets:
          type: array
          items:
            $ref: '#/components/schemas/Widget'

Swagger UI отобразит следующий пример для Warehouse в запросах и ответах:

{
  "id": 4321,
  "location": "Sample location",
  "widgets": [
    "id": 1234,
    "description": "An example widget",
    "cost": 0.1
  ]
}