Компоненты и ссылки

Components — переиспользуемые объекты

Объект components хранит определения, на которые ссылаются другие части документа. Сами по себе они ни на что не влияют, пока на них нет ссылок.

Поле	Содержимое
schemas	Схемы данных.
responses	Ответы.
parameters	Параметры.
examples	Примеры.
requestBodies	Тела запросов.
headers	Заголовки.
securitySchemes	Схемы безопасности.
links	Связи между операциями.
callbacks	Обратные вызовы.

Имена компонентов могут содержать латинские буквы, цифры, ., - и _.

openapi: 3.0.3
info:
  title: API заказов
  version: 1.0.0
paths:
  /orders:
    get:
      summary: Список заказов
      parameters:
        - $ref: '#/components/parameters/Page'
        - $ref: '#/components/parameters/Size'
      responses:
        '200':
          description: Страница заказов
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/OrderPage'
        '401':
          $ref: '#/components/responses/Unauthorized'
components:
  parameters:
    Page:
      name: page
      in: query
      schema:
        type: integer
        minimum: 0
        default: 0
    Size:
      name: size
      in: query
      schema:
        type: integer
        minimum: 1
        maximum: 100
        default: 20
  responses:
    Unauthorized:
      description: Требуется авторизация
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
  schemas:
    Order:
      type: object
      properties:
        id:
          type: string
          format: uuid
        status:
          type: string
    OrderPage:
      type: object
      required: [items, total]
      properties:
        items:
          type: array
          items:
            $ref: '#/components/schemas/Order'
        total:
          type: integer
    Error:
      type: object
      required: [code, message]
      properties:
        code:
          type: string
        message:
          type: string

Ссылки $ref

$ref заменяет объект ссылкой на определение в другом месте. Ссылка — URI; часть после # — это JSON Pointer (RFC 6901), путь по ключам документа:

Ссылка	Куда ведёт
'#/components/schemas/Order'	схема Order в этом же файле
'common.yaml#/components/schemas/Money'	схема в соседнем файле
'../shared/errors.yaml#/Error'	объект Error в файле из другой папки
'order.schema.yaml'	весь файл — например, файл с одной схемой

В JSON Pointer символ / в имени ключа записывается как ~1, а ~ — как ~0. Например, ссылка на путь /orders/{id}: '#/paths/~1orders~1{id}'.

Ссылку в YAML пишите в кавычках — иначе # будет прочитан как начало комментария.

Многофайловые спецификации в «Помощнике SA»

Большую спецификацию удобно разделить на файлы: общие схемы, ошибки, параметры. В проекте «Помощника SA»:

• файлы-артефакты раскладываются по папкам проекта; путь в дереве папок — это адрес для $ref, например common/money.yaml#/Money;
• ссылки разрешаются относительно папки, в которой лежит ссылающийся файл, .. — переход вверх;
• Ctrl+клик (Cmd+клик) по $ref открывает нужный файл в новой вкладке и переходит к определению;
• предпросмотр строится по открытому файлу, поэтому схемы из других файлов в нём не раскрываются — для проверки полной документации соберите спецификацию в один файл (bundling) внешними инструментами или временно перенесите определения в components.

Reference Object и соседние поля

В OpenAPI 3.0 объект со $ref не может содержать других полей — они игнорируются. Чтобы, например, добавить описание к ссылке на схему, оберните её в allOf:

properties:
  billingAddress:
    description: Адрес для выставления счёта
    allOf:
      - $ref: '#/components/schemas/Address'