Запросы и ответы

Request Body — тело запроса

Поле	Описание
description	Описание (CommonMark).
content	Обязательное. Описания тела по типам содержимого (application/json, multipart/form-data …).
required	Обязательно ли тело; по умолчанию false.

Ключ в content — тип содержимого (media type) или диапазон: text/plain, text/*, */*; при нескольких подходящих выбирается самый конкретный.

Media Type — описание содержимого

Поле	Описание
schema	Схема содержимого.
example, examples	Пример или набор именованных примеров (Example Object).
encoding	Для multipart и application/x-www-form-urlencoded: как кодируются отдельные поля.

openapi: 3.0.3
info:
  title: API заказов
  version: 1.0.0
paths:
  /orders:
    post:
      summary: Создать заказ
      requestBody:
        required: true
        description: Состав заказа
        content:
          application/json:
            schema:
              type: object
              required: [items]
              properties:
                items:
                  type: array
                  minItems: 1
                  items:
                    type: object
                    required: [sku, qty]
                    properties:
                      sku:
                        type: string
                      qty:
                        type: integer
                        minimum: 1
                comment:
                  type: string
            examples:
              simple:
                summary: Один товар
                value:
                  items:
                    - sku: A-1
                      qty: 2
      responses:
        '201':
          description: Заказ создан
          headers:
            Location:
              description: Адрес созданного заказа
              schema:
                type: string
          content:
            application/json:
              schema:
                type: object
                properties:
                  id:
                    type: string
                    format: uuid
        '400':
          description: Ошибка в запросе
        default:
          description: Непредвиденная ошибка

Загрузка файлов

Файл описывается строкой с format: binary (или byte для Base64). Для загрузки вместе с другими полями используется multipart/form-data; encoding уточняет тип содержимого отдельной части.

requestBody:
  content:
    multipart/form-data:
      schema:
        type: object
        properties:
          orderId:
            type: string
          scan:
            type: string
            format: binary
      encoding:
        scan:
          contentType: image/png, image/jpeg
    application/octet-stream:
      schema:
        type: string
        format: binary

Responses — ответы

Ключ — код ответа HTTP в кавычках ('200'), диапазон ('2XX', '4XX', '5XX') или default — ответ для всех кодов, не описанных явно. Нужно описать хотя бы один ответ; хорошая практика — описать успешный ответ и основные ошибки. Явно указанный код имеет приоритет над диапазоном.

Response

Поле	Описание
description	Обязательное. Описание ответа.
headers	Заголовки ответа (Header Object; имя — ключ, без name и in).
content	Тело ответа по типам содержимого.
links	Связи с другими операциями.

Заголовок Content-Type в headers не описывается — он следует из content.

Header — заголовок

Header устроен как Parameter, но без name (имя — ключ в headers) и in (всегда header).

responses:
  '429':
    description: Слишком много запросов
    headers:
      Retry-After:
        description: Через сколько секунд повторить запрос
        schema:
          type: integer
      X-RateLimit-Remaining:
        schema:
          type: integer

Example — пример

Поле	Описание
summary	Краткое описание.
description	Подробное описание.
value	Значение примера.
externalValue	Ссылка на пример во внешнем файле (вместо value).

Links — связи между операциями

Link показывает, как значение из ответа использовать в другой операции — например, id созданного заказа для запроса его статуса.

responses:
  '201':
    description: Заказ создан
    links:
      GetOrder:
        operationId: getOrder
        parameters:
          orderId: '$response.body#/id'
        description: id из ответа можно передать в GET /orders/{orderId}