Пути и операции

Paths — пути

Объект paths содержит относительные пути к ресурсам. Путь начинается с / и добавляется к адресу сервера из servers (обычная конкатенация). Сегменты в фигурных скобках — шаблоны пути: их значения передаются параметрами in: path.

paths:
  /orders:
    get: ...
  /orders/{orderId}:
    get: ...
  /orders/{orderId}/items:
    get: ...

Правила:

• пути с одинаковой структурой, отличающиеся только именем шаблона, считаются одинаковыми и недопустимы (/orders/{id} и /orders/{orderId});
• при совпадении конкретный путь имеет приоритет над шаблоном: /orders/mine выбирается раньше /orders/{id};
• у каждого шаблона пути должен быть описан параметр in: path с таким же именем.

Path Item — операции пути

Поле	Описание
summary, description	Описание, общее для всех операций пути.
get, put, post, delete, options, head, patch, trace	Операции по HTTP-методам.
servers	Серверы только для этого пути.
parameters	Параметры, общие для всех операций пути; операция может переопределить параметр с тем же name и in.
$ref	Ссылка на описание пути в другом месте.

Operation — операция

Поле	Описание
tags	Теги для группировки в документации.
summary	Краткое описание (одна строка).
description	Подробное описание (CommonMark).
operationId	Уникальный идентификатор операции во всём API; генераторы кода делают из него имя метода.
parameters	Параметры операции.
requestBody	Тело запроса.
responses	Обязательное. Возможные ответы.
callbacks	Обратные вызовы (запросы, которые API отправит клиенту).
deprecated	true — операция устарела и не рекомендуется.
security	Схемы безопасности операции (заменяют корневые; [] — операция без авторизации).
servers	Серверы только для этой операции.
externalDocs	Ссылка на внешнюю документацию.

openapi: 3.0.3
info:
  title: API заказов
  version: 1.0.0
paths:
  /orders/{orderId}:
    parameters:
      - name: orderId
        in: path
        required: true
        description: Идентификатор заказа
        schema:
          type: string
          format: uuid
    get:
      tags: [Заказы]
      summary: Получить заказ
      operationId: getOrder
      responses:
        '200':
          description: Заказ
        '404':
          description: Заказ не найден
    delete:
      tags: [Заказы]
      summary: Отменить заказ
      description: |
        Отменить можно только неоплаченный заказ.
      operationId: cancelOrder
      deprecated: true
      responses:
        '204':
          description: Заказ отменён
        '409':
          description: Заказ уже оплачен

Callbacks — обратные вызовы

Callback описывает запросы, которые сервер отправит клиенту — например, вебхук после оплаты. Ключ — выражение, по которому вычисляется адрес: {$request.body#/callbackUrl} берёт адрес из тела исходного запроса.

paths:
  /payments:
    post:
      summary: Создать платёж
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                amount:
                  type: number
                callbackUrl:
                  type: string
                  format: uri
      responses:
        '201':
          description: Платёж создан
      callbacks:
        paymentStatus:
          '{$request.body#/callbackUrl}':
            post:
              requestBody:
                content:
                  application/json:
                    schema:
                      type: object
                      properties:
                        status:
                          type: string
              responses:
                '200':
                  description: Уведомление принято

Кроме тела запроса, в выражениях доступны $url, $method, $request.path.имя, $request.query.имя, $request.header.имя, $response.body#/указатель и $response.header.имя.