Параметры

Параметр описывает одно значение, которое передаётся в пути, строке запроса, заголовке или cookie. Параметр однозначно определяется парой name + in.

Поля Parameter

Поле	Описание
name	Обязательное. Имя параметра (чувствительно к регистру). Для in: path должно совпадать с шаблоном в пути.
in	Обязательное. Где передаётся: path, query, header или cookie.
description	Описание (CommonMark).
required	Обязателен ли параметр. Для in: path обязательно true; для остальных по умолчанию false.
deprecated	Параметр устарел.
allowEmptyValue	Можно ли передать пустое значение (?flag=); только для query, использовать не рекомендуется.
schema	Схема значения.
content	Альтернатива schema для сложных значений (например, JSON в строке запроса); ровно одна запись.
example, examples	Пример или набор именованных примеров.
style, explode	Способ сериализации массивов и объектов (см. ниже).

Задаётся либо schema, либо content — не оба сразу.

Заголовки Accept, Content-Type и Authorization параметрами не описываются: первые два выводятся из content, а авторизация описывается схемами безопасности.

Параметры в пути, запросе, заголовке и cookie

openapi: 3.0.3
info:
  title: Каталог
  version: 1.0.0
paths:
  /categories/{categoryId}/products:
    get:
      summary: Товары категории
      parameters:
        - name: categoryId
          in: path
          required: true
          schema:
            type: integer
        - name: search
          in: query
          description: Поиск по названию
          schema:
            type: string
            maxLength: 100
        - name: page
          in: query
          schema:
            type: integer
            minimum: 0
            default: 0
        - name: size
          in: query
          schema:
            type: integer
            minimum: 1
            maximum: 100
            default: 20
        - name: X-Request-Id
          in: header
          description: Идентификатор запроса для трассировки
          schema:
            type: string
            format: uuid
        - name: region
          in: cookie
          schema:
            type: string
            enum: [msk, spb]
      responses:
        '200':
          description: Страница товаров

Массивы и объекты: style и explode

Как значение массива или объекта превращается в строку, определяют style и explode.

style	Где	Массив [3, 4, 5] при explode: false	При explode: true
form (по умолчанию для query, cookie)	query, cookie	?id=3,4,5	?id=3&id=4&id=5
simple (по умолчанию для path, header)	path, header	3,4,5	3,4,5
label	path	.3.4.5	.3.4.5
matrix	path	;id=3,4,5	;id=3;id=4;id=5
spaceDelimited	query	?id=3%204%205	—
pipeDelimited	query	?id=3|4|5	—
deepObject	query	—	?filter[status]=paid&filter[city]=msk (объект)

explode по умолчанию true для style: form и false для остальных.

parameters:
  - name: status
    in: query
    description: Несколько статусов через запятую
    style: form
    explode: false
    schema:
      type: array
      items:
        type: string
        enum: [new, paid, shipped]
  - name: filter
    in: query
    style: deepObject
    explode: true
    schema:
      type: object
      properties:
        city:
          type: string
        minTotal:
          type: number

Сложные значения через content

parameters:
  - name: coordinates
    in: query
    content:
      application/json:
        schema:
          type: object
          required: [lat, lon]
          properties:
            lat:
              type: number
            lon:
              type: number

Примеры

parameters:
  - name: sort
    in: query
    schema:
      type: string
    examples:
      byDate:
        summary: Сначала новые
        value: -createdAt
      byPrice:
        summary: По возрастанию цены
        value: price