Спецификация OpenAPI 3.1.0 (русская редакция)
Версия 3.1.0
В данном документе ключевые слова "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY" и "OPTIONAL" должны интерпретироваться так, как описано в BCP 14 RFC2119 RFC8174 только в тех случаях, когда они написаны заглавными буквами.
Данный документ лицензируется в соответствии с Лицензией Apache, Версия 2.0.
Введение
Спецификация OpenAPI (OAS) определяет стандартный языково-независимый интерфейс для HTTP API, который позволяет как людям, так и компьютерам обнаруживать и понимать возможности сервиса без доступа к исходному коду, документации или осуществления сетевого трафика. Правильно определенный консумер может понять и взаимодействовать с удаленным сервисом с минимальным количеством логики реализации.
Описание OpenAPI может быть использовано инструментами для генерации документации для отображения API, инструментами для генерации кода для создания серверов и клиентов на различных языках программирования, инструментами для тестирования и многими другими случаями использования.
Содержание
- Определения
- Спецификация
- Версии
- Формат
- Структура документа
- Типы данных
- Форматирование текста
- Относительные ссылки в URI
- Относительные ссылки в URL
- Схема
- Объект OpenAPI
- Объект Info
- Объект Contact
- Объект License
- Объект Server
- Объект Server Variable
- Объект Components
- Объект Paths
- Объект Path Item
- Объект Operation
- Объект External Documentation
- Объект Parameter
- Объект Request Body
- Объект Media Type
- Объект Encoding
- Объект Responses
- Объект Response
- Объект Callback
- Объект Example
- Объект Link
- Объект Header
- Объект Tag
- Объект Reference
- Объект Schema
- Объект Discriminator
- Объект XML
- Объект Security Scheme
- Объект OAuth Flows
- Объект OAuth Flow
- Объект Security Requirement
- Расширения спецификации
- Фильтрация безопасности
- Приложение А: История изменений
Определения
Документ OpenAPI
Самостоятельный или композитный ресурс, который определяет или описывает API или элементы API. Документ OpenAPI ДОЛЖЕН содержать как минимум одно поле paths, поле components или поле webhooks. Документ OpenAPI использует и соответствует спецификации OpenAPI.
Шаблонизация пути
Шаблонизация пути относится к использованию шаблонных выражений, ограниченных фигурными скобками ({}), для обозначения секции пути URL, которую можно заменить с помощью параметров пути.
Каждое шаблонное выражение в пути ДОЛЖНО соответствовать параметру пути, который включен в Объект Path Item самого пути и/или в каждой из Операций Объекта Path Item. Исключение составляет случай, когда элемент пути пустой, например, из-за ограничений ACL, и соответствующие параметры пути не требуются.
Значение для этих параметров пути НЕ ДОЛЖНО содержать неквалифицированные символы "generic syntax", описанные в RFC3986: косая черта (/
), вопросительный знак (?
) или решетка (#
).
Типы медиа
Определения типов медиа распределены по нескольким ресурсам. Определения типов медиа ДОЛЖНЫ соответствовать RFC6838.
Некоторые примеры возможных определений типов медиа:
text/plain; charset=utf-8
application/json
application/vnd.github+json
application/vnd.github.v3+json
application/vnd.github.v3.raw+json
application/vnd.github.v3.text+json
application/vnd.github.v3.html+json
application/vnd.github.v3.full+json
application/vnd.github.v3.diff
application/vnd.github.v3.patch
Коды состояния HTTP
Коды состояния HTTP используются для указания статуса выполненной операции. Доступные коды состояния определены в RFC7231, а зарегистрированные коды состояния перечислены в Реестре кодов состояния IANA.
Спецификация
Версии
Спецификация OpenAPI имеет версию в формате major
.minor
.patch
. major
.minor
версия строки (например, 3.1
) ДОЛЖНА определять набор функций OAS. .patch
версии исправляют ошибки или предоставляют уточнения этого документа, а не набор функций. Инструментарий, поддерживающий OAS 3.1, ДОЛЖЕН быть совместим с всеми версиями OAS 3.1.*. Патч-версия НЕ ДОЛЖНА учитываться инструментарием, не делая различий между 3.1.0
и 3.1.1
, например.
Иногда некомпатибельные изменения могут быть внесены в minor
версии OAS, где предполагается, что их влияние незначительно по сравнению с предоставленной пользой.
Документ OpenAPI, совместимый с OAS 3.*.*, содержит обязательное поле openapi
, которое определяет версию используемой OAS.
Формат
Документ OpenAPI, соответствующий спецификации OpenAPI, представляет собой JSON-объект, который может быть представлен как в формате JSON, так и в формате YAML.
Например, если поле имеет значение массива, будет использоваться представление массива в JSON:
Все имена полей в спецификации чувствительны к регистру. Это относится ко всем полям, используемым в качестве ключей в карте, за исключением случаев, когда явно указано, что ключи не чувствительны к регистру.Схема предоставляет два типа полей: фиксированные поля с объявленным именем и поля по шаблону, которые объявляют регулярное выражение для имени поля.
Поля по шаблону ДОЛЖНЫ иметь уникальные имена внутри содержащего объекта.
Для сохранения возможности обратного преобразования между форматами YAML и JSON РЕКОМЕНДУЕТСЯ использовать YAML версии 1.2 с дополнительными ограничениями:
- Теги ДОЛЖНЫ быть ограничены теми, которые разрешены правилами JSON Schema.
- Ключи, используемые в картах YAML, ДОЛЖНЫ быть скалярными строками, определенными правилами YAML Failsafe schema.
Примечание: Хотя API могут быть определены в документах OpenAPI как в формате YAML, так и в формате JSON, тела запросов и ответов API и другие содержимое не обязательно должны быть в формате JSON или YAML.
Структура документа
Документ OpenAPI МОЖЕТ состоять из одного документа или быть разделен на несколько связанных частей по усмотрению автора. В последнем случае используются Объекты Ссылок
и Объекты Схемы
с ключевыми словами $ref
.
РЕКОМЕНДУЕТСЯ, чтобы корневой документ OpenAPI имел имя openapi.json
или openapi.yaml
.
Типы данных
Типы данных в OAS основаны на типах, поддерживаемых JSON Schema Specification Draft 2020-12. Обратите внимание, что integer
в качестве типа также поддерживается и определяется как число JSON без дробной или экспоненциальной части. Модели определяются с использованием Объекта Схемы, который является надмножеством спецификации JSON Schema Draft 2020-12.
Как определено в словаре валидации JSON Schema, типы данных могут иметь необязательное свойство-модификатор: format
. OAS определяет дополнительные форматы, чтобы дать дополнительные детали для примитивных типов данных.
Определенные форматы в OAS:
type | format | Комментарии |
---|---|---|
integer | int32 | знаковые 32 бита |
integer | int64 | знаковые 64 бита (также известные как long) |
number | float | |
number | double | |
string | password | Подсказка для UI для затемнения ввода. |
Форматирование текста с использованием разметки
Во всей спецификации поля description
отмечены как поддерживающие форматирование с использованием разметки CommonMark. Когда инструменты OpenAPI отображают форматированный текст, ОНИ ДОЛЖНЫ поддерживать, как минимум, синтаксис markdown, описанный в CommonMark 0.27. Инструментарий МОЖЕТ выбирать игнорировать некоторые функции CommonMark для обеспечения безопасности.
Относительные ссылки в URI
Если не указано иное, все свойства, являющиеся URI, МОГУТ быть относительными ссылками, как определено в RFC3986.
Относительные ссылки, включая ссылки в Объектах Ссылок
, полях $ref
Объекта PathItem
, полях operationRef
Объекта Link
и полях externalValue
Объекта Example
, разрешаются с использованием ссылочного документа в качестве базового URI в соответствии с RFC3986.
Если URI содержит идентификатор фрагмента, то фрагмент должен быть разрешен согласно механизму разрешения фрагментов указанного документа. Если представление указанного документа является JSON или YAML, то идентификатор фрагмента ДОЛЖЕН интерпретироваться как JSON-указатель согласно RFC6901.
Относительные ссылки в Объектах Схемы
, включая те, которые появляются в значениях $id
, используют ближайший родительский $id
в качестве базового URI, как описано в JSON Schema Specification Draft 2020-12. Если ни одна из родительских схем не содержит $id
, то базовый URI ДОЛЖЕН быть определен в соответствии с RFC3986.
Относительные ссылки в URL
Если не указано иное, все свойства, являющиеся URL, МОГУТ быть относительными ссылками, как определено в
RFC3986. Если не указано иное, относительные ссылки разрешаются с использованием URL, определенных в Объекте Сервер
в качестве базового URL. Обратите внимание, что они сами МОГУТ быть относительными по отношению к ссылочному документу.
Объект OpenAPI
Это корневой объект документа OpenAPI.
Фиксированные поля
Имя поля | Тип | Описание |
---|---|---|
openapi | string | ОБЯЗАТЕЛЬНО. Эта строка ДОЛЖНА содержать номер версии OpenAPI Specification, используемой в документе OpenAPI. Поле openapi ДОЛЖНО использоваться инструментами для интерпретации документа OpenAPI. Это не связано со строкой info.version в API. |
info | Объект Info | ОБЯЗАТЕЛЬНО. Предоставляет метаданные об API. Эти метаданные МОГУТ использоваться инструментами по необходимости. |
jsonSchemaDialect | string | Значение по умолчанию для ключевого слова $schema в Объектах Схемы, содержащихся в данном документе OpenAPI. Это ДОЛЖНО быть в форме URI. |
servers | [Объект Сервера] | Массив объектов Сервер, которые предоставляют информацию о подключении к целевому серверу. Если свойство servers не предоставлено или является пустым массивом, то значение по умолчанию будет содержать Объект Сервера с значением url равным / . |
paths | Объект Путей | Доступные пути и операции для API. |
webhooks | Map[string , Объект Path Item | Объект Ссылки] ] | Входящие webhooks, которые МОГУТ быть получены в рамках этого API, и которые API-потребитель МОЖЕТ выбрать для реализации. Тесно связан с возможностью использования callbacks , эта секция описывает запросы, инициируемые не через вызов API, например, через внешнюю регистрацию. Имя ключа является уникальной строкой для ссылки на каждый webhook, в то время как (опционально ссылочный) Объект Path Item описывает запрос, который может быть инициирован API-провайдером и ожидаемые ответы. Доступен пример. |
components | Объект Компонентов | Элемент для хранения различных схем в документе. |
security | [Объект Требований Безопасности] | Объявление механизмов безопасности, которые могут использоваться в API. Список значений включает альтернативные объекты требований безопасности, которые могут быть использованы. Для авторизации запроса достаточно удовлетворить одному из объектов требований безопасности. Отдельные операции могут переопределять это определение. Чтобы сделать безопасность необязательной, в массив может быть включено пустое требование безопасности ({} ). |
tags | [Объект Тега] | Список тегов, используемых в документе с дополнительной метаданными. Порядок тегов может использоваться для их упорядочивания инструментами разбора. Не все теги, используемые в Объекте Операции, должны быть объявлены. Необъявленные теги могут быть организованы случайным образом или на основе логики инструментов. Каждое имя тега в списке ДОЛЖНО быть уникальным. |
externalDocs | Объект Внешней Документации | Дополнительная внешняя документация. |
Этот объект МОЖЕТ быть расширен с помощью Расширений Спецификации.
Объект Info
Объект предоставляет метаданные об API. Эти метаданные МОГУТ использоваться клиентами при необходимости и МОГУТ отображаться в инструментах редактирования или генерации документации для удобства.
Фиксированные поля
Имя поля | Тип | Описание |
---|---|---|
title | string | ОБЯЗАТЕЛЬНО. Название API. |
summary | string | Краткое описание API. |
description | string | Описание API. Может использоваться синтаксис CommonMark для представления форматированного текста. |
termsOfService | string | URL Условий использования API. ДОЛЖЕН быть в формате URL. |
contact | Объект Контакта | Контактная информация об открытом API. |
license | Объект Лицензии | Информация о лицензии для открытого API. |
version | string | ОБЯЗАТЕЛЬНО. Версия документа OpenAPI (которая отличается от версии спецификации OpenAPI или версии реализации API). |
Этот объект МОЖЕТ быть расширен с помощью Расширений Спецификации.
Пример объекта Info
{
"title": "Sample Pet Store App",
"summary": "Менеджер зоомагазина.",
"description": "Это образец сервера для зоомагазина.",
"termsOfService": "https://example.com/terms/",
"contact": {
"name": "Поддержка API",
"url": "https://www.example.com/support",
"email": "support@example.com"
},
"license": {
"name": "Apache 2.0",
"url": "https://www.apache.org/licenses/LICENSE-2.0.html"
},
"version": "1.0.1"
}
title: Sample Pet Store App
summary: Менеджер зоомагазина.
description: Это образец сервера для зоомагазина.
termsOfService: https://example.com/terms/
contact:
name: Поддержка API
url: https://www.example.com/support
email: support@example.com
license:
name: Apache 2.0
url: https://www.apache.org/licenses/LICENSE-2.0.html
version: 1.0.1
Объект Contact (Контакт)
Информация для связи с открытым API.
Фиксированные поля
Этот объект МОЖЕТ быть расширен с помощью Расширений Спецификации.
Пример объекта Contact (Контакт)
{
"name": "Поддержка API",
"url": "https://www.example.com/support",
"email": "support@example.com"
}
Объект License (Лицензия)
Информация о лицензии для открытого API.
Фиксированные поля
Имя поля | Тип | Описание |
---|---|---|
name | string | ОБЯЗАТЕЛЬНО. Название лицензии, используемой для API. |
identifier | string | Выражение лицензии SPDX для API. Поле identifier является взаимоисключающим с полем url . |
url | string | URL лицензии, используемой для API. ДОЛЖЕН быть в формате URL. Поле url является взаимоисключающим с полем identifier . |
Этот объект МОЖЕТ быть расширен с помощью Расширений Спецификации.
Пример объекта License (Лицензия)
Объект Server (Сервер)
Объект, представляющий сервер.
Фиксированные поля
Имя поля | Тип | Описание |
---|---|---|
url | string | ОБЯЗАТЕЛЬНО. URL целевого хоста. Этот URL поддерживает переменные сервера и МОЖЕТ быть относительным, чтобы указать, что местоположение хоста относительно местоположения, где обслуживается документ OpenAPI. Подстановки переменных будут выполнены, когда переменная указана в { скобках} . |
description | string | Дополнительная строка, описывающая хост, указанный в URL. Синтаксис CommonMark МОЖЕТ использоваться для представления форматированного текста. |
variables | Map[string , Объект Переменной Сервера] | Карта между именем переменной и ее значением. Значение используется для подстановки в URL-шаблон сервера. |
Этот объект МОЖЕТ быть расширен с помощью Расширений Спецификации.
Пример объекта Server (Сервер)
Описание одного сервера:
Ниже показано, как описать несколько серверов, например, в объекте OpenAPI servers
:
{
"servers": [
{
"url": "https://development.gigantic-server.com/v1",
"description": "Development server"
},
{
"url": "https://staging.gigantic-server.com/v1",
"description": "Staging server"
},
{
"url": "https://api.gigantic-server.com/v1",
"description": "Production server"
}
]
}
servers:
- url: https://development.gigantic-server.com/v1
description: Development server
- url: https://staging.gigantic-server.com/v1
description: Staging server
- url: https://api.gigantic-server.com/v1
description: Production server
Ниже показано, как использовать переменные для конфигурации сервера:
{
"servers": [
{
"url": "https://{username}.gigantic-server.com:{port}/{basePath}",
"description": "The production API server",
"variables": {
"username": {
"default": "demo",
"description": "this value is assigned by the service provider, in this example `gigantic-server.com`"
},
"port": {
"enum": [
"8443",
"443"
],
"default": "8443"
},
"basePath": {
"default": "v2"
}
}
}
]
}
servers:
- url: https://{username}.gigantic-server.com:{port}/{basePath}
description: The production API server
variables:
username:
# заметьте! здесь нет enum, значит, это открытое значение
default: demo
description: this value is assigned by the service provider, in this example `gigantic-server.com`
port:
enum:
- '8443'
- '443'
default: '8443'
basePath:
# открытое значение означает возможность использовать специальные базовые пути, назначенные провайдером, по умолчанию `v2`
default: v2
Объект Server Variable (Серверная Переменная)
Объект, представляющий переменную сервера для подстановки в URL-шаблон сервера.
Фиксированные поля
Имя поля | Тип | Описание |
---|---|---|
enum | [string ] | Перечисление строковых значений, которые будут использоваться, если варианты подстановки представляют собой ограниченный набор. Массив НЕ ДОЛЖЕН быть пустым. |
default | string | ОБЯЗАТЕЛЬНО. Значение по умолчанию для подстановки, которое будет отправлено, если не указано альтернативное значение. Обратите внимание, что это отличается от обработки значения по умолчанию в Объекте Схемы, поскольку в этих случаях значения параметров являются необязательными. Если определено enum , значение ДОЛЖНО существовать в значениях перечисления. |
description | string | Опциональное описание переменной сервера. Синтаксис CommonMark МОЖЕТ использоваться для представления форматированного текста. |
Этот объект МОЖЕТ быть расширен с помощью Расширений Спецификации.
Объект Сomponents (Компоненты)
Содержит набор повторно используемых объектов для различных аспектов OAS. Все объекты, определенные внутри объекта компонентов, не будут иметь эффекта на API, если они явно не будут ссылаться извне объекта компонентов.
Фиксированные поля
Имя поля | Тип | Описание |
---|---|---|
schemas | Map[string , Объект Схемы] | Объект, содержащий повторно используемые Объекты Схемы. |
responses | Map[string , Объект Ответа | Объект Ссылки] | Объект, содержащий повторно используемые Объекты Ответа. |
parameters | Map[string , Объект Параметра | Объект Ссылки] | Объект, содержащий повторно используемые Объекты Параметра. |
examples | Map[string , Объект Примера | Объект Ссылки] | Объект, содержащий повторно используемые Объекты Примера. |
requestBodies | Map[string , Объект Тела Запроса | Объект Ссылки] | Объект, содержащий повторно используемые Объекты Тела Запроса. |
headers | Map[string , Объект Заголовка | Объект Ссылки] | Объект, содержащий повторно используемые Объекты Заголовка. |
securitySchemes | Map[string , Объект Схемы Безопасности | Объект Ссылки] | Объект, содержащий повторно используемые Объекты Схемы Безопасности. |
links | Map[string , Объект Ссылки | Объект Ссылки] | Объект, содержащий повторно используемые Объекты Ссылки. |
callbacks | Map[string , Объект Callback | Объект Ссылки] | Объект, содержащий повторно используемые Объекты Callback. |
pathItems | Map[string , Объект Элемента Пути | Объект Ссылки] | Объект, содержащий повторно используемые Объекты Элемента Пути. |
Этот объект МОЖЕТ быть расширен с помощью Расширений Спецификации.
Все фиксированные поля, указанные выше, являются объектами, которые ДОЛЖНЫ использовать ключи, соответствующие регулярному выражению: ^[a-zA-Z0-9\.\-_]+$
.
Примеры Имен Полей:
Пример объекта Components (Компоненты)
"components": {
"schemas": {
"GeneralError": {
"type": "object",
"properties": {
"code": {
"type": "integer",
"format": "int32"
},
"message": {
"type": "string"
}
}
},
"Category": {
"type": "object",
"properties": {
"id": {
"type": "integer",
"format": "int64"
},
"name": {
"type": "string"
}
}
},
"Tag": {
"type": "object",
"properties": {
"id": {
"type": "integer",
"format": "int64"
},
"name": {
"type": "string"
}
}
}
},
"parameters": {
"skipParam": {
"name": "skip",
"in": "query",
"description": "количество пропускаемых элементов",
"required": true,
"schema": {
"type": "integer",
"format": "int32"
}
},
"limitParam": {
"name": "limit",
"in": "query",
"description": "максимальное количество возвращаемых элементов",
"required": true,
"schema" : {
"type": "integer",
"format": "int32"
}
}
},
"responses": {
"NotFound": {
"description": "Сущность не найдена."
},
"IllegalInput": {
"description": "Недопустимые данные для операции."
},
"GeneralError": {
"description": "Общая ошибка",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/GeneralError"
}
}
}
}
},
"securitySchemes": {
"api_key": {
"type": "apiKey",
"name": "api_key",
"in": "header"
},
"petstore_auth": {
"type": "oauth2",
"flows": {
"implicit": {
"authorizationUrl": "https://example.org/api/oauth/dialog",
"scopes": {
"write:pets": "изменение данных о животных",
"read:pets": "чтение данных о ваших животных"
}
}
}
}
}
}
components:
schemas:
GeneralError:
type: object
properties:
code:
type: integer
format: int32
message:
type: string
Category:
type: object
properties:
id:
type: integer
format: int64
name:
type: string
Tag:
type: object
properties:
id:
type: integer
format: int64
name:
type: string
parameters:
skipParam:
name: skip
in: query
description: количество пропускаемых элементов
required: true
schema:
type: integer
format: int32
limitParam:
name: limit
in: query
description: максимальное количество возвращаемых элементов
required: true
schema:
type: integer
format: int32
responses:
NotFound:
description: Сущность не найдена.
IllegalInput:
description: Недопустимые данные для операции.
GeneralError:
description: Общая ошибка
content:
application/json:
schema:
$ref: '#/components/schemas/GeneralError'
securitySchemes:
api_key:
type: apiKey
name: api_key
in: header
petstore_auth:
type: oauth2
flows:
implicit:
authorizationUrl: https://example.org/api/oauth/dialog
scopes:
write:pets: изменение данных о животных
read:pets: чтение данных о ваших животных
Объект Paths (Пути)
Содержит относительные пути к отдельным конечным точкам и их операциям. Путь добавляется к URL из Server Object
для формирования полного URL. Пути МОГУТ быть пустыми из-за ограничений списка контроля доступа (ACL).
Поля с шаблоном
Шаблон поля | Тип | Описание |
---|---|---|
/{path} | Path Item Object | Относительный путь к отдельной конечной точке. Имя поля ДОЛЖНО начинаться с косой черты (/ ). Путь добавляется (без относительного разрешения URL) к развернутому URL из поля url в Server Object , чтобы сформировать полный URL. Допускается использование шаблонов пути. При сопоставлении URL с конкретными (не шаблонными) путями сопоставление будет происходить сначала с конкретными путями, а затем с шаблонными. Шаблонные пути с одинаковой иерархией, но разными именами шаблонов, НЕ МОГУТ существовать, так как они идентичны. В случае неоднозначного сопоставления выбор будет зависеть от инструментария. |
Объект может быть расширен с помощью расширений спецификации.
Сопоставление шаблонов пути
Предположим, что имеются следующие пути, то конкретное определение /pets/mine
будет сопоставлено первым, если будет использовано:
Следующие пути считаются идентичными и недопустимыми:
Следующее может привести к неоднозначному разрешению:
Пример объекта Paths (Пути)
{
"/pets": {
"get": {
"description": "Возвращает всех питомцев из системы, на которых у пользователя есть доступ",
"responses": {
"200": {
"description": "Список питомцев.",
"content": {
"application/json": {
"schema": {
"type": "array",
"items": {
"$ref": "#/components/schemas/pet"
}
}
}
}
}
}
}
}
}
/pets:
get:
description: Возвращает всех питомцев
responses:
'200':
description: Список питомцев.
content:
application/json:
schema:
type: array
items:
$ref: '#/components/schemas/pet'
Объект Path Item (Элемент Пути)
Описывает операции, доступные для отдельного пути. Объект Path Item может быть пустым из-за ограничений списка контроля доступа (ACL). Сам путь все равно отображается во вьюере документации, но они не будут знать, какие операции и параметры доступны.
Фиксированные поля
Имя поля | Тип | Описание |
---|---|---|
$ref | string | Позволяет ссылаться на определение этого элемента пути. Ссылочная структура ДОЛЖНА иметь форму объекта Path Item. Если поле объекта Path Item указано и в определенном объекте, и в ссылочном объекте, то поведение не определено. См. правила разрешения относительных ссылок. |
summary | string | Необязательное краткое описание в виде строки, предназначенное для применения ко всем операциям в этом пути. |
description | string | Необязательное описание в виде строки, предназначенное для применения ко всем операциям в этом пути. Может использоваться для представления форматированного текста. |
get | Operation Object | Описание операции GET для этого пути. |
put | Operation Object | Описание операции PUT для этого пути. |
post | Operation Object | Описание операции POST для этого пути. |
delete | Operation Object | Описание операции DELETE для этого пути. |
options | Operation Object | Описание операции OPTIONS для этого пути. |
head | Operation Object | Описание операции HEAD для этого пути. |
patch | Operation Object | Описание операции PATCH для этого пути. |
trace | Operation Object | Описание операции TRACE для этого пути. |
servers | [Server Object] | Альтернативный массив server , который будет использоваться для всех операций в этом пути. |
parameters | [Parameter Object | Reference Object] | Список параметров, применимых ко всем операциям, описанным в этом пути. Эти параметры могут быть переопределены на уровне операции, но не могут быть удалены оттуда. Список НЕ МОЖЕТ включать повторяющиеся параметры. Уникальный параметр определяется комбинацией имени и расположения. Список может использовать Reference Object, чтобы ссылаться на параметры, определенные в компонентах объекта OpenAPI. |
Объект может быть расширен с помощью расширений спецификации.
Объект Operation (Операции)
Описывает одну операцию API для пути.
Фиксированные поля
Название поля | Тип | Описание |
---|---|---|
tags | [string ] | Список тегов для управления документацией API. Теги могут использоваться для логической группировки операций по ресурсам или любым другим критериям. |
summary | string | Краткое описание того, что делает операция. |
description | string | Подробное объяснение поведения операции. Может использоваться синтаксис CommonMark для представления текста с разметкой. |
externalDocs | Объект внешней документации | Дополнительная внешняя документация для этой операции. |
operationId | string | Уникальная строка, используемая для идентификации операции. Идентификатор должен быть уникальным среди всех операций, описанных в API. Значение идентификатора операции чувствительно к регистру. Инструменты и библиотеки могут использовать идентификатор операции для ее однозначной идентификации, поэтому РЕКОМЕНДУЕТСЯ следовать общим соглашениям по наименованию в программировании. |
parameters | [Объект параметра | Объект ссылки] | Список параметров, применимых к этой операции. Если параметр уже определен в объекте пути, новое определение будет его переопределять, но никогда не удалит его. Список НЕ ДОЛЖЕН включать дублирующиеся параметры. Уникальный параметр определяется комбинацией имени и расположения. Список может использовать объект ссылки для ссылки на параметры, определенные в компонентах OpenAPI. |
requestBody | Объект тела запроса | Объект ссылки | Тело запроса, применимое к этой операции. requestBody полностью поддерживается в методах HTTP, где спецификация HTTP 1.1 RFC7231 явно определяет семантику для тел запросов. В других случаях, когда спецификация HTTP неоднозначна (например, GET, HEAD и DELETE), requestBody допускается, но не имеет четко определенной семантики и РЕКОМЕНДУЕТСЯ избегать его использования, если возможно. |
responses | Объект ответов | Список возможных ответов, возвращаемых при выполнении этой операции. |
callbacks | Map[string , Объект обратного вызова | Объект ссылки] | Карта возможных асинхронных обратных вызовов, связанных с родительской операцией. Ключ - это уникальный идентификатор объекта обратного вызова. Каждое значение в карте - это Объект обратного вызова, который описывает запрос, который может быть инициирован API-провайдером, и ожидаемые ответы. |
deprecated | boolean | Объявляет данную операцию как устаревшую. Потребители ДОЛЖНЫ избегать использования объявленной операции. Значение по умолчанию - false . |
security | [Объект требования безопасности] | Объявление механизмов безопасности, которые могут использоваться для данной операции. Список значений включает альтернативные объекты требований безопасности, которые могут быть использованы. Для авторизации запроса требуется удовлетворение только одному из объектов требований безопасности. Чтобы сделать безопасность необязательной, в массив можно включить пустое требование безопасности ({} ). Это определение переопределяет любое объявленное на верхнем уровне требование безопасности security . Чтобы удалить объявление требования безопасности на верхнем уровне, можно использовать пустой массив. |
servers | [Объект сервера] | Альтернативный массив server для обслуживания данной операции. Если в объекте элемента пути или на уровне корня указан альтернативный объект server , он будет переопределен этим значением. |
Этот объект МОЖЕТ быть расширен с помощью расширений спецификации.
Пример объекта Operation (Oперации)
{
"tags": [
"pet"
],
"summary": "Обновляет информацию о питомце в магазине с использованием формы",
"operationId": "updatePetWithForm",
"parameters": [
{
"name": "petId",
"in": "path",
"description": "ID питомца, котороно нужно обновить",
"required": true,
"schema": {
"type": "string"
}
}
],
"requestBody": {
"content": {
"application/x-www-form-urlencoded": {
"schema": {
"type": "object",
"properties": {
"name": {
"description": "Обновленное имя питомца",
"type": "string"
},
"status": {
"description": "Обновленный статус питомца",
"type": "string"
}
},
"required": ["status"]
}
}
}
},
"responses": {
"200": {
"description": "Питомец обновлен.",
"content": {
"application/json": {},
"application/xml": {}
}
},
"405": {
"description": "Метод не разрешен",
"content": {
"application/json": {},
"application/xml": {}
}
}
},
"security": [
{
"petstore_auth": [
"write:pets",
"read:pets"
]
}
]
}
tags:
- pet
summary: Обновляет информацию о питомце в магазине с использованием формы
operationId: updatePetWithForm
parameters:
- name: petId
in: path
description: ID питомца, который нужно обновить
required: true
schema:
type: string
requestBody:
content:
'application/x-www-form-urlencoded':
schema:
type: object
properties:
name:
description: Обновленное имя питомца
type: string
status:
description: Обновленный статус питомца
type: string
required:
- status
responses:
'200':
description: Питомец обновлен.
content:
'application/json': {}
'application/xml': {}
'405':
description: Метод не разрешен
content:
'application/json': {}
'application/xml': {}
security:
- petstore_auth:
- write:pets
- read:pets
Объект externalDocumentation (Внешняя документация)
Позволяет ссылаться на внешний ресурс для расширенной документации.
Фиксированные поля
Название поля | Тип | Описание |
---|---|---|
description | string | Описание целевой документации. Может использоваться синтаксис CommonMark для представления форматированного текста. |
url | string | ОБЯЗАТЕЛЬНО. URL для целевой документации. Должен иметь форму URL. |
Этот объект МОЖЕТ быть расширен с помощью расширений спецификации.
Пример объекта externalDocumentation (внешней документации)
Объект Parameter (Параметр)
Описывает отдельный параметр операции.
Уникальный параметр определяется комбинацией имени и местоположения параметра.
Местоположения параметра
Местоположение параметра определяется полем in
и может иметь четыре возможных значения: * path - используется вместе с шаблонами пути, где значение параметра фактически является частью URL операции. Это не включает хост или базовый путь API. Например, в /items/{itemId}
параметр пути - это itemId
. * query - параметры, добавляемые в URL. Например, в /items?id=###
параметр запроса - это id
. * header - пользовательские заголовки, ожидаемые как часть запроса. Обратите внимание, что имена заголовков нечувствительны к регистру, согласно RFC7230. * cookie - используется для передачи конкретного значения cookie в API.
Фиксированные поля
Название поля | Тип | Описание |
---|---|---|
name | string | ОБЯЗАТЕЛЬНО. Имя параметра. Имена параметров чувствительны к регистру.
|
in | string | ОБЯЗАТЕЛЬНО. Местоположение параметра. Возможные значения: "query" , "header" , "path" или "cookie" . |
description | string | Краткое описание параметра. Может содержать примеры использования. Можно использовать синтаксис CommonMark для представления форматированного текста. |
required | boolean | Определяет, является ли этот параметр обязательным. Если местоположение параметра равно "path" , это поле ОБЯЗАТЕЛЬНО и его значение ДОЛЖНО быть true . В противном случае, поле МОЖЕТ быть включено, и его значение по умолчанию равно false . |
deprecated | boolean | Указывает, что параметр устарел и РЕКОМЕНДУЕТСЯ перестать его использовать. Значение по умолчанию равно false . |
allowEmptyValue | boolean | Устанавливает возможность передачи параметров со значением "пусто". Это действительно только для параметров типа query и позволяет отправлять параметр со значением "пусто". Значение по умолчанию равно false . Если используется style , и если поведение равно n/a (не может быть сериализовано), значение allowEmptyValue будет проигнорировано. НЕ РЕКОМЕНДУЕТСЯ использовать это свойство, так как оно может быть удалено в будущих версиях. |
Правила сериализации параметра определяются двумя способами. Для простых сценариев схема и стиль могут описывать структуру и синтаксис значения параметра.
Название поля | Тип | Описание |
---|---|---|
style | string | Описывает, как будет сериализовано значение параметра в зависимости от типа значения параметра. Значения по умолчанию (на основе значения in ): для query - form ; для path - simple ; для header - simple ; для cookie - form . |
explode | boolean | Если это значение true , параметры типа array или object генерируют отдельные параметры для каждого значения массива или каждой пары ключ-значение объекта. Для других типов параметров это свойство не имеет эффекта. Когда style равен form , значение по умолчанию равно true . Для всех других стилей значение по умолчанию равно false . |
allowReserved | boolean | Определяет, должно ли значение параметра разрешать зарезервированные символы, определенные в RFC3986 :/?#[]@!$&'()*+,;= ), чтобы быть включенными без кодирования в процентах. Это свойство применяется только к параметрам со значением in равным query . Значение по умолчанию равно false . |
schema | Объект схемы | Схема, определяющая тип, используемый для параметра. |
example | Любой | Пример возможного значения параметра. Пример ДОЛЖЕН соответствовать указанной схеме и свойствам кодирования, если они указаны. Поле example является взаимоисключающим с полем examples . Кроме того, если используется ссылка на schema , содержащая пример, значение example ПЕРЕКРЫВАЕТ пример, предоставленный схемой. Чтобы представить примеры типов носителей, которые нельзя естественно представить в формате JSON или YAML, строковое значение может содержать пример с использованием экранирования, если необходимо. |
examples | Map[ string , Объект примера | Объект ссылки] | Примеры возможных значений параметра. Каждый пример ДОЛЖЕН содержать значение в правильном формате, указанном в кодировке параметра. Поле examples является взаимоисключающим с полем example . Кроме того, если используется ссылка на schema , содержащая пример, значение examples ПЕРЕКРЫВАЕТ пример, предоставленный схемой. |
Для более сложных сценариев свойство content
может определять тип медиа и схему параметра. Параметр ДОЛЖЕН содержать либо свойство schema
, либо свойство content
, но не оба сразу. Когда предоставляются example
или examples
вместе с объектом schema
, пример ДОЛЖЕН следовать предписанной стратегии сериализации параметра.
Название поля | Тип | Описание |
---|---|---|
content | Map[string , Объект медиа] | Карта, содержащая представления параметра. Ключ - это тип медиа, а значение его описание. Карта ДОЛЖНА содержать только одну запись. |
Значения стиля
Для поддержки обычных способов сериализации простых параметров определен набор значений style
.
style | type | in | Комментарии |
---|---|---|---|
matrix | primitive , array , object | path | Параметры в стиле пути, определенные в RFC6570 |
label | primitive , array , object | path | Параметры в стиле метки, определенные в RFC6570 |
form | primitive , array , object | query , cookie | Параметры в стиле формы, определенные в RFC6570. Этот вариант заменяет collectionFormat значением csv (когда explode равно false ) или multi (когда explode равно true ) в OpenAPI 2.0. |
simple | array | path , header | Параметры в простом стиле, определенные в RFC6570. Этот вариант заменяет collectionFormat значением csv в OpenAPI 2.0. |
spaceDelimited | array , object | query | Пробелом разделенные значения массива или объекта. Этот вариант заменяет collectionFormat значением ssv в OpenAPI 2.0. |
pipeDelimited | array , object | query | Значения массива или объекта, разделенные вертикальной чертой. Этот вариант заменяет collectionFormat значением pipes в OpenAPI 2.0. |
deepObject | object | query | Предоставляет простой способ отображения вложенных объектов с использованием параметров формы. |
Примеры стиля
Предположим, что параметр с именем color
имеет одно из следующих значений:
style | explode | empty | string | array | object |
---|---|---|---|---|---|
matrix | false | ;color | ;color=blue | ;color=blue,black,brown | ;color=R,100,G,200,B,150 |
matrix | true | ;color | ;color=blue | ;color=blue;color=black;color=brown | ;R=100;G=200;B=150 |
label | false | . | .blue | .blue.black.brown | .R.100.G.200.B.150 |
label | true | . | .blue | .blue.black.brown | .R=100.G=200.B=150 |
form | false | color= | color=blue | color=blue,black,brown | color=R,100,G,200,B,150 |
form | true | color= | color=blue | color=blue&color=black&color=brown | R=100&G=200&B=150 |
simple | false | n/a | blue | blue,black,brown | R,100,G,200,B,150 |
simple | true | n/a | blue | blue,black,brown | R=100,G=200,B=150 |
spaceDelimited | false | n/a | n/a | blue%20black%20brown | R%20100%20G%20200%20B%20150 |
pipeDelimited | false | n/a | n/a | blue|black|brown | R|100|G|200|B|150 |
deepObject | true | n/a | n/a | n/a | color[R]=100&color[G]=200&color[B]=150 |
This object MAY be extended with Specification Extensions.
Примеры объекта параметра
Параметр заголовка с массивом чисел 64-битного целого:
{
"name": "token",
"in": "header",
"description": "токен, передаваемый как заголовок",
"required": true,
"schema": {
"type": "array",
"items": {
"type": "integer",
"format": "int64"
}
},
"style": "simple"
}
name: token
in: header
description: токен, передаваемый как заголовок
required: true
schema:
type: array
items:
type: integer
format: int64
style: simple
Параметр пути со значением строкового типа:
{
"name": "username",
"in": "path",
"description": "имя пользователя для получения",
"required": true,
"schema": {
"type": "string"
}
}
name: username
in: path
description: имя пользователя для получения
required: true
schema:
type: string
Необязательный параметр запроса со значением строкового типа, позволяющий передавать несколько значений, повторяя параметр запроса:
{
"name": "id",
"in": "query",
"description": "ID объекта для получения",
"required": false,
"schema": {
"type": "array",
"items": {
"type": "string"
}
},
"style": "form",
"explode": true
}
name: id
in: query
description: ID объекта для получения
required: false
schema:
type: array
items:
type: string
style: form
explode: true
Свободный параметр запроса, позволяющий неопределенные параметры определенного типа:
{
"in": "query",
"name": "freeForm",
"schema": {
"type": "object",
"additionalProperties": {
"type": "integer"
},
},
"style": "form"
}
Сложный параметр, использующий content
для определения сериализации:
{
"in": "query",
"name": "coordinates",
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"lat",
"long"
],
"properties": {
"lat": {
"type": "number"
},
"long": {
"type": "number"
}
}
}
}
}
}
in: query
name: coordinates
content:
application/json:
schema:
type: object
required:
- lat
- long
properties:
lat:
type: number
long:
type: number
Объект Request Body
Описывает единственное тело запроса.
Фиксированные поля
Имя поля | Тип | Описание |
---|---|---|
description | string | Краткое описание тела запроса. Может содержать примеры использования. Для представления текста допускается использование формата CommonMark. |
content | Map[string , Media Type Object] | ТРЕБУЕТСЯ. Содержимое тела запроса. Ключ - тип медиа или диапазон типов медиа, а значение описывает это содержимое. Если запрос соответствует нескольким ключам, применяется наиболее конкретный ключ, например, text/plain переопределяет text/*. |
required | boolean | Определяет, является ли тело запроса обязательным в запросе. По умолчанию равно false . |
Этот объект может быть расширен с помощью расширений спецификации.
Примеры объекта Request Body
Тело запроса с ссылкой на определение модели.
{
"description": "пользователь для добавления в систему",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/User"
},
"examples": {
"user" : {
"summary": "Пример пользователя",
"externalValue": "https://foo.bar/examples/user-example.json"
}
}
},
"application/xml": {
"schema": {
"$ref": "#/components/schemas/User"
},
"examples": {
"user" : {
"summary": "Пример пользователя в XML",
"externalValue": "https://foo.bar/examples/user-example.xml"
}
}
},
"text/plain": {
"examples": {
"user" : {
"summary": "Пример пользователя в виде обычного текста",
"externalValue": "https://foo.bar/examples/user-example.txt"
}
}
},
"*/*": {
"examples": {
"user" : {
"summary": "Пример пользователя в другом формате",
"externalValue": "https://foo.bar/examples/user-example.whatever"
}
}
}
}
}
description: пользователь для добавления в систему
content:
'application/json':
schema:
$ref: '#/components/schemas/User'
examples:
user:
summary: Пример пользователя
externalValue: 'https://foo.bar/examples/user-example.json'
'application/xml':
schema:
$ref: '#/components/schemas/User'
examples:
user:
summary: Пример пользователя в XML
externalValue: 'https://foo.bar/examples/user-example.xml'
'text/plain':
examples:
user:
summary: Пример пользователя в виде обычного текста
externalValue: 'https://foo.bar/examples/user-example.txt'
'*/*':
examples:
user:
summary: Пример пользователя в другом формате
externalValue: 'https://foo.bar/examples/user-example.whatever'
Параметр тела запроса, являющийся массивом строковых значений:
{
"description": "пользователь для добавления в систему",
"required": true,
"content": {
"text/plain": {
"schema": {
"type": "array",
"items": {
"type": "string"
}
}
}
}
}
description: пользователь для добавления в систему
required: true
content:
text/plain:
schema:
type: array
items:
type: string
Объект Media Type
Каждый объект Media Type предоставляет схему и примеры для типа медиа, определенного по ключу.
Фиксированные поля
Имя поля | Тип | Описание |
---|---|---|
schema | Schema Object | Схема, определяющая содержимое запроса, ответа или параметра. |
example | Любой | Пример типа медиа. Объект примера ДОЛЖЕН быть в правильном формате, указанном для типа медиа. Поле example и поле examples взаимоисключающие. Более того, если привязана ссылка на schema , которая содержит пример, значение поля example ПЕРЕКРЫВАЕТ пример, предоставленный схемой. |
examples | Map[ string , Example Object | Reference Object] | Примеры для типа медиа. Каждый объект примера ДОЛЖЕН соответствовать типу медиа и указанной схеме, если она есть. Поле examples и поле example взаимоисключающие. Более того, если привязана ссылка на schema , которая содержит пример, значение поля examples ПЕРЕКРЫВАЕТ пример, предоставленный схемой. |
encoding | Map[string , Encoding Object] | Соответствие между именем свойства и информацией о его кодировании. Ключ, являющийся именем свойства, ДОЛЖЕН существовать в схеме в виде свойства. Объект кодирования ДОЛЖЕН применяться только к объектам requestBody , когда тип медиа является multipart или application/x-www-form-urlencoded . |
Этот объект может быть расширен с помощью расширений спецификации.
Примеры типа медиа
{
"application/json": {
"schema": {
"$ref": "#/components/schemas/Pet"
},
"examples": {
"cat" : {
"summary": "Пример кота",
"value":
{
"name": "Пушистик",
"petType": "Cat",
"color": "Белый",
"gender": "мужской",
"breed": "Персидский"
}
},
"dog": {
"summary": "Пример собаки с именем кота",
"value" : {
"name": "Пума",
"petType": "Dog",
"color": "Черный",
"gender": "Женский",
"breed": "Смешанная"
}
},
"frog": {
"$ref": "#/components/examples/frog-example"
}
}
}
}
application/json:
schema:
$ref: "#/components/schemas/Pet"
examples:
cat:
summary: Пример кота
value:
name: Пушистик
petType: Cat
color: Белый
gender: мужской
breed: Персидский
dog:
summary: Пример собаки с именем кота
value:
name: Пума
petType: Dog
color: Черный
gender: Женский
breed: Смешанная
frog:
$ref: "#/components/examples/frog-example"
Соображения для загрузки файлов
В отличие от спецификации 2.0, содержимое файлового ввода/вывода в OpenAPI описывается с теми же семантиками, что и для любого другого типа схемы.
В отличие от спецификации 3.0, ключевое слово format
не влияет на кодирование содержимого схемы. Схема JSON использует ключевое слово contentEncoding
, которое может использоваться для указания Content-Encoding
для схемы. Ключевое слово contentEncoding
поддерживает все кодировки, определенные в RFC4648, включая "base64" и "base64url", а также "quoted-printable" из RFC2045. Кодировка, указанная ключевым словом contentEncoding
, независима от кодировки, указанной в заголовке Content-Type
запроса или ответа или метаданных multipart-тела. При наличии обоих кодировок сначала применяется кодировка, указанная в contentEncoding
, а затем кодировка, указанная в заголовке Content-Type
.
Схема JSON также предлагает ключевое слово contentMediaType
. Однако, если тип медиа уже указан в ключе объекта Media Type или в поле contentType
Encoding Object, то ключевое слово contentMediaType
будет проигнорировано, если оно присутствует.
Примеры:
Содержимое, передаваемое в бинарном (octet-stream) формате, может не содержать schema
:
Бинарное содержимое, передаваемое с использованием кодирования base64:
Обратите внимание, что Content-Type
остается image/png
, описывая семантику полезной нагрузки. Свойства JSON Schema type
и contentEncoding
объясняют, что полезная нагрузка передается в виде текста. Ключевое слово contentMediaType
JSON Schema технически избыточно, но может быть использовано инструментами JSON Schema, которые могут не знать о контексте OpenAPI.
Эти примеры применяются как к входным данным файлового ввода, так и к выходным данным.
Пример requestBody
для отправки файла в операции POST
может выглядеть следующим образом:
Кроме того, можно указать конкретные типы медиа:
# можно указать несколько конкретных типов медиа:
requestBody:
content:
# бинарный файл типа png или jpeg
image/jpeg: {}
image/png: {}
Для загрузки нескольких файлов необходимо использовать медиа-тип multipart
:
requestBody:
content:
multipart/form-data:
schema:
properties:
# Свойство с именем 'file' будет использоваться для всех файлов.
file:
type: array
items: {}
Как видно из раздела о multipart/form-data
ниже, пустая схема для items
указывает на медиа-тип application/octet-stream
.
Поддержка тел запроса в формате x-www-form-urlencoded
Для отправки содержимого с использованием кодирования формы по URL по RFC1866, можно использовать следующее определение:
requestBody:
content:
application/x-www-form-urlencoded:
schema:
type: object
properties:
id:
type: string
format: uuid
address:
# сложные типы преобразуются в строку для поддержки RFC 1866
type: object
properties: {}
В этом примере содержимое в requestBody
ДОЛЖНО быть преобразовано в строку согласно RFC1866, когда оно передается на сервер. Кроме того, сложный объект поля address
будет преобразован в строку.
При передаче сложных объектов в application/x-www-form-urlencoded
типе контента, стратегия сериализации свойств может быть описана в свойстве style
объекта Encoding Object
как form
.
Особенности multipart
-контента
Обычно multipart/form-data
используется как Content-Type
при передаче тел запросов в операции. В отличие от спецификации 2.0, schema
ОБЯЗАТЕЛЬНО для определения входных параметров операции при использовании multipart
-контента. Это поддерживает сложные структуры, а также механизмы для передачи нескольких файлов.
В теле запроса multipart/form-data
каждое свойство схемы или каждый элемент свойства массива схемы занимает свою секцию в передаваемых данных, внутренний заголовок которой описан в RFC7578. Стратегия сериализации для каждого свойства тела запроса multipart/form-data
может быть указана в связанном Encoding Object
.
При передаче типов multipart
, разделители (boundaries) МОГУТ использоваться для разделения разделов передаваемого содержимого. Таким образом, для multipart
определены следующие значения по умолчанию для Content-Type
:
- Если свойство является примитивным типом или массивом примитивных значений, то значение по умолчанию для
Content-Type
-text/plain
. - Если свойство является сложным типом или массивом сложных значений, то значение по умолчанию для
Content-Type
-application/json
. - Если свойство имеет тип
string
с указаниемcontentEncoding
, то значение по умолчанию дляContent-Type
-application/octet-stream
.
В соответствии со спецификацией JSON Schema, если указано contentMediaType
без наличия contentEncoding
, то оно рассматривается так, будто присутствует contentEncoding: identity
. Хотя это полезно для вставки текстовых документов, таких как text/html
, в JSON-строки, это бесполезно для части multipart/form-data
, так как приводит к тому, что документ обрабатывается как text/plain
вместо его фактического типа медиа. Используйте объект Encoding Object
без contentMediaType
, если не требуется contentEncoding
.
Примеры:
requestBody:
content:
multipart/form-data:
schema:
type: object
properties:
id:
type: string
format: uuid
address:
# значение по умолчанию для объектов - `application/json`
type: object
properties: {}
profileImage:
# значение по умолчанию для ресурсов с кодированием на уровне приложения - `text/plain`
type: string
contentMediaType: image/png
contentEncoding: base64
children:
# значение по умолчанию для массивов основано на типе элементов (`text/plain` в данном случае)
type: array
items:
type: string
addresses:
# значение по умолчанию для массивов основано на типе элементов (показан объект, поэтому `application/json` в этом примере)
type: array
items:
type: object
$ref: '#/components/schemas/Address'
Введен атрибут encoding
, который дает возможность контролировать сериализацию частей запросов с multipart
-форматом. Этот атрибут применим ТОЛЬКО к телам запросов с типами multipart
и application/x-www-form-urlencoded
.
Объект кодирования (Encoding Object)
Описание кодирования, применяемого к конкретному свойству схемы.
Фиксированные поля
Имя поля | Тип | Описание |
---|---|---|
contentType | string | Тип контента для кодирования определенного свойства. Значение по умолчанию зависит от типа свойства: для object – application/json ; для array – значение по умолчанию определяется на основе внутреннего типа; для всех остальных случаев значение по умолчанию – application/octet-stream . Значение может быть конкретным типом медиа (например, application/json ), шаблоном медиа (например, image/* ) или списком, разделенным запятыми, из двух типов. |
headers | Map[string , Объект заголовка (Header Object) | Объект ссылки (Reference Object)] | Карта, позволяющая предоставлять дополнительную информацию в виде заголовков, например Content-Disposition . Это поле игнорируется, если тип медиа тела запроса не является multipart . |
style | string | Определяет, как будет сериализовано конкретное значение свойства в зависимости от его типа. См. Объект параметра (Parameter Object) для получения подробной информации о свойстве style . Поведение следует тем же значениям, что и у параметров query , включая значения по умолчанию. Это поле игнорируется, если тип медиа тела запроса не является application/x-www-form-urlencoded или multipart/form-data . Если значение явно определено, то значение contentType (неявное или явное) будет игнорироваться. |
explode | boolean | Если значение равно true , то значения свойств типов array или object создают отдельные параметры для каждого значения массива или пары ключ-значение в объекте. Для других типов свойств это свойство не имеет эффекта. Если style равно form , значение по умолчанию – true . Для всех остальных стилей значение по умолчанию – false . Это поле игнорируется, если тип медиа тела запроса не является application/x-www-form-urlencoded или multipart/form-data . Если значение явно определено, то значение contentType (неявное или явное) будет игнорироваться. |
allowReserved | boolean | Определяет, разрешено ли значение параметра содержать зарезервированные символы, определенные в RFC3986 :/?#[]@!$&'()*+,;= без кодирования в процентах. Значение по умолчанию – false . Это поле игнорируется, если тип медиа тела запроса не является application/x-www-form-urlencoded или multipart/form-data . Если значение явно определено, то значение contentType (неявное или явное) будет игнорироваться. |
Этот объект МОЖЕТ быть расширен с помощью Расширений спецификации (Specification Extensions).
Пример объекта кодирования
requestBody:
content:
multipart/form-data:
schema:
type: object
properties:
id:
# значение по умолчанию - text/plain
type: string
format: uuid
address:
# значение по умолчанию - application/json
type: object
properties: {}
historyMetadata:
# требуется формат XML!
description: метаданные в формате XML
type: object
properties: {}
profileImage: {}
encoding:
historyMetadata:
# требуется XML Content-Type в кодировке utf-8
contentType: application/xml; charset=utf-8
profileImage:
# принимать только png/jpeg
contentType: image/png, image/jpeg
headers:
X-Rate-Limit-Limit:
description: Количество разрешенных запросов в текущем периоде
schema:
type: integer
Объект ответов (Responses Object)
Контейнер для ожидаемых ответов операции. Контейнер сопоставляет код HTTP-ответа с ожидаемым ответом.
Документация не обязана охватывать все возможные коды HTTP-ответов, поскольку они могут быть неизвестны заранее. Однако документация должна охватывать успешный ответ операции и все известные ошибки.
default
МОЖЕТ использоваться в качестве объекта ответа по умолчанию для всех HTTP-кодов, которые не покрываются отдельно в объекте Responses Object
.
Responses Object
ДОЛЖЕН содержать как минимум один код ответа, и если предоставлен только один код ответа, то ЭТО ДОЛЖЕН быть ответ на успешный вызов операции.
Поля по шаблону
Шаблон поля | Тип | Описание |
---|---|---|
Код состояния HTTP | Объект ответа (Response Object) | Объект ссылки (Reference Object) | В качестве имени свойства может использоваться любой код состояния HTTP, но только одно свойство на каждый код, для описания ожидаемого ответа для этого кода состояния HTTP. Это поле ДОЛЖНО быть заключено в кавычки (например, "200") для обеспечения совместимости между JSON и YAML. Чтобы определить диапазон кодов ответа, это поле МОЖЕТ содержать заглавный символ-заполнитель X . Например, 2XX представляет все коды ответа между [200-299] . Разрешаются только следующие определения диапазона: 1XX , 2XX , 3XX , 4XX и 5XX . Если ответ определен с использованием явного кода, явное определение кода имеет приоритет перед определением диапазона для этого кода. |
Этот объект МОЖЕТ быть расширен с помощью Расширений спецификации (Specification Extensions).
Пример объекта Responses
Ответ 200 для успешной операции и ответ по умолчанию для других (предполагается ошибка):
{
"200": {
"description": "питомец для возврата",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Pet"
}
}
}
},
"default": {
"description": "Неожиданная ошибка",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorModel"
}
}
}
}
}
'200':
description: питомец для возврата
content:
application/json:
schema:
$ref: '#/components/schemas/Pet'
default:
description: Неожиданная ошибка
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorModel'
Объект ответа (Response Object)
Описывает один ответ от операции API, включая проектные, статические links
к операциям на основе ответа.
Фиксированные поля
Имя поля | Тип | Описание |
---|---|---|
description | string | ТРЕБУЕТСЯ. Описание ответа. Допускается использование синтаксиса CommonMark для представления форматированного текста. |
headers | Map[string , Объект заголовка (Header Object) | Объект ссылки (Reference Object)] | Отображает имя заголовка на его определение. RFC7230 утверждает, что имена заголовков нечувствительны к регистру. Если заголовок ответа определен с именем "Content-Type" , он ДОЛЖЕН быть проигнорирован. |
content | Map[string , Объект медиатипа (Media Type Object)] | Карта, содержащая описания возможных ответных нагрузок. Ключ - это медиатип или диапазон медиатипов, а значение описывает его. Для ответов, которые соответствуют нескольким ключам, применяется только наиболее конкретный ключ. Например, text/plain преобладает над text/* |
links | Map[string , Объект ссылки (Link Object) | Объект ссылки (Reference Object)] | Карта операций, ссылки на которые могут быть выполнены из ответа. Ключ карты - это краткое имя ссылки, соответствующее ограничениям имен для Объектов компонентов (Component Objects). |
Этот объект МОЖЕТ быть расширен с помощью Расширений спецификации (Specification Extensions).
Примеры объекта Response
Ответ с массивом сложного типа:
{
"description": "Ответ на массив сложных объектов",
"content": {
"application/json": {
"schema": {
"type": "array",
"items": {
"$ref": "#/components/schemas/VeryComplexType"
}
}
}
}
}
description: Ответ на массив сложных объектов
content:
application/json:
schema:
type: array
items:
$ref: '#/components/schemas/VeryComplexType'
Ответ со строковым типом:
{
"description": "Простой строковый ответ",
"content": {
"text/plain": {
"schema": {
"type": "string"
}
}
}
}
Ответ в виде простого текста с заголовками:
{
"description": "Простой строковый ответ",
"content": {
"text/plain": {
"schema": {
"type": "string",
"example": "Вау!"
}
}
},
"headers": {
"
X-Rate-Limit-Limit": {
"description": "Количество разрешенных запросов в текущем периоде",
"schema": {
"type": "integer"
}
},
"X-Rate-Limit-Remaining": {
"description": "Количество оставшихся запросов в текущем периоде",
"schema": {
"type": "integer"
}
},
"X-Rate-Limit-Reset": {
"description": "Количество секунд, оставшихся в текущем периоде",
"schema": {
"type": "integer"
}
}
}
}
description: Простой строковый ответ
content:
text/plain:
schema:
type: string
example: 'Вау!'
headers:
X-Rate-Limit-Limit:
description: Количество разрешенных запросов в текущем периоде
schema:
type: integer
X-Rate-Limit-Remaining:
description: Количество оставшихся запросов в текущем периоде
schema:
type: integer
X-Rate-Limit-Reset:
description: Количество секунд, оставшихся в текущем периоде
schema:
type: integer
Ответ без значения возврата:
Объект Callback
Словарь возможных асинхронных вызовов, связанных с родительской операцией. Каждое значение в словаре - это Объект элемента пути (Path Item Object), описывающий набор запросов, которые могут быть инициированы провайдером API, и ожидаемые ответы. Значение ключа, используемое для идентификации объекта элемента пути, представляет собой выражение, вычисляемое во время выполнения, которое идентифицирует URL, используемый для запроса обратного вызова.
Для описания входящих запросов от провайдера API независимо от другого вызова API используйте поле webhooks
.
Поля с шаблонами
Шаблон | Тип | Описание |
---|---|---|
{expression} | Объект элемента пути (Path Item Object) | Объект ссылки (Reference Object) | Объект элемента пути или ссылка на него, используемый для определения запроса обратного вызова и ожидаемых ответов. Доступен полный пример. |
Этот объект МОЖЕТ быть расширен с помощью Расширений спецификации (Specification Extensions).
Ключевое выражение
Ключ, который идентифицирует Объект элемента пути (Path Item Object), является выражением времени выполнения, которое может быть вычислено в контексте запроса/ответа HTTP во время выполнения для определения URL, который будет использоваться для запроса обратного вызова. Простым примером может быть $request.body#/url
. Однако, с помощью выражения времени выполнения можно получить доступ ко всему HTTP-сообщению. Это включает доступ к любой части тела, на которую может ссылаться JSON Pointer RFC6901.
Например, учитывая следующий HTTP-запрос:
POST /subscribe/myevent?queryUrl=https://clientdomain.com/stillrunning HTTP/1.1
Host: example.org
Content-Type: application/json
Content-Length: 187
{
"failedUrl" : "https://clientdomain.com/failed",
"successUrls" : [
"https://clientdomain.com/fast",
"https://clientdomain.com/medium",
"https://clientdomain.com/slow"
]
}
201 Created
Location: https://example.org/subscription/1
В следующих примерах показано, как вычисляются
различные выражения, при условии, что операция обратного вызова имеет параметр пути с именем eventType
и параметр запроса с именем queryUrl
.
Выражение | Значение |
---|---|
$url | https://example.org/subscribe/myevent?queryUrl=https://clientdomain.com/stillrunning |
$method | POST |
$request.path.eventType | myevent |
$request.query.queryUrl | https://clientdomain.com/stillrunning |
$request.header.content-Type | application/json |
$request.body#/failedUrl | https://clientdomain.com/failed |
$request.body#/successUrls/2 | https://clientdomain.com/medium |
$response.header.Location | https://example.org/subscription/1 |
Примеры объекта Callback
В следующем примере используется предоставленный пользователем параметр строки запроса queryUrl
для определения URL обратного вызова. Это пример использования объекта обратного вызова для описания обратного вызова WebHook, который сопровождает операцию подписки, чтобы разрешить регистрацию для WebHook.
myCallback:
'{$request.query.queryUrl}':
post:
requestBody:
description: Callback payload
content:
'application/json':
schema:
$ref: '#/components/schemas/SomePayload'
responses:
'200':
description: callback successfully processed
В следующем примере показан обратный вызов, где сервер захардкожен, но параметры строки запроса заполняются из свойств id
и email
в теле запроса.
transactionCallback:
'http://notificationServer.com?transactionId={$request.body#/id}&email={$request.body#/email}':
post:
requestBody:
description: Callback payload
content:
'application/json':
schema:
$ref: '#/components/schemas/SomePayload'
responses:
'200':
description: callback successfully processed
Объект Примера
Фиксированные поля
Имя поля | Тип | Описание |
---|---|---|
summary | string | Краткое описание примера. |
description | string | Подробное описание примера. Может использоваться синтаксис CommonMark для отображения форматированного текста. |
value | Любой | Встроенный литеральный пример. Поле value и поле externalValue исключают друг друга. Для представления примеров типов контента, которые нельзя естественным образом представить в формате JSON или YAML, используйте строковое значение для содержания примера с необходимым экранированием. |
externalValue | string | URI, указывающий на литеральный пример. Это позволяет ссылаться на примеры, которые нельзя легко включить в документы JSON или YAML. Поле value и поле externalValue исключают друг друга. См. правила разрешения относительных ссылок. |
Этот объект МОЖЕТ быть расширен с помощью Расширений спецификации (Specification Extensions).
Во всех случаях ожидается, что значение примера совместимо с схемой типа его ассоциированного значения. Реализации инструментов МОЖЕТ выбрать автоматическую проверку совместимости и отклонить значения примеров, если они несовместимы.
Примеры объекта Example
В теле запроса:
requestBody:
content:
'application/json':
schema:
$ref: '#/components/schemas/Address'
examples:
foo:
summary: Пример foo
value: {"foo": "bar"}
bar:
summary: Пример bar
value: {"bar": "baz"}
'application/xml':
examples:
xmlExample:
summary: Это пример в формате XML
externalValue: 'https://example.org/examples/address-example.xml'
'text/plain':
examples:
textExample:
summary: Это текстовый пример
externalValue: 'https://foo.bar/examples/address-example.txt'
В параметре:
parameters:
- name: 'zipCode'
in: 'query'
schema:
type: 'string'
format: 'zip-code'
examples:
zip-example:
$ref: '#/components/examples/zip-example'
В ответе:
responses:
'200':
description: Ваша запись на посещение автомобиля была забронирована
content:
application/json:
schema:
$ref: '#/components/schemas/SuccessResponse'
examples:
confirmation-success:
$ref: '#/components/examples/confirmation-success'
Объект Link
Объект Link
представляет возможную ссылку для ответа на этапе проектирования. Присутствие ссылки не гарантирует возможность успешного вызова ее, оно лишь обеспечивает известную связь и механизм перехода между ответами и другими операциями.
В отличие от динамических ссылок (т.е. ссылок, предоставленных внутри тела ответа), механизм связывания OAS не требует наличия информации о ссылке в ответе во время выполнения.
Для вычисления ссылок и предоставления инструкций по их выполнению используется выражение времени выполнения, которое позволяет получить доступ к значениям операции и использовать их в качестве параметров при вызове связанной операции.
Фиксированные поля
Имя поля | Тип | Описание |
---|---|---|
operationRef | string | Относительная или абсолютная ссылка на операцию OAS. Это поле взаимоисключающее с полем operationId и ДОЛЖНО ссылаться на Объект операции (Operation Object). Относительные значения operationRef МОГУТ использоваться для поиска существующего Объекта операции (Operation Object) в определении OpenAPI. См. правила разрешения относительных ссылок. |
operationId | string | Имя существующей разрешаемой операции OAS, определенное с уникальным operationId . Это поле взаимоисключающее с полем operationRef . |
parameters | Map[string , Any | {expression}] | Карта, представляющая параметры, передаваемые в операцию, определенную с помощью operationId или идентифицируемую через operationRef . Ключ является именем параметра, которое будет использоваться, а значение может быть константой или выражением, которое будет вычислено и передано в связанную операцию. Имя параметра может быть квалифицировано с использованием расположения параметра parameter location [{in}.]{name} для операций, использующих одно и то же имя параметра в разных местах (например, path.id). |
requestBody | Any | {expression} | Литеральное значение или {expression}, которое будет использоваться в качестве тела запроса при вызове целевой операции. |
description | string | Описание ссылки. Может использоваться синтаксис CommonMark для форматирования текста. |
server | Объект сервера (Server Object) | Объект сервера, который будет использоваться целевой операцией. |
Этот объект МОЖЕТ быть расширен с помощью Расширений спецификации (Specification Extensions).
Связанная операция ДОЛЖНА быть идентифицирована с помощью operationRef
или operationId
. В случае использования operationId
, он ДОЛЖЕН быть уникальным и разрешен в рамках документа OAS. Из-за возможных коллизий имен синтаксис operationRef
предпочтительнее при использовании в документах OpenAPI с внешними ссылками.
Примеры
Вычисление ссылки из операции запроса, где $request.path.id
используется для передачи параметра запроса в связанную операцию.
paths:
/users/{id}:
parameters:
- name: id
in: path
required: true
description: идентификатор пользователя, как userId
schema:
type: string
get:
responses:
'200':
description: возвращаемый пользователь
content:
application/json:
schema:
type: object
properties:
uuid: # уникальный идентификатор пользователя
type: string
format: uuid
links:
address:
# идентификатор целевой операции
operationId: getUserAddress
parameters:
# получить поле `id` из параметра пути запроса с именем `id`
userId: $request.path.id
# элемент пути связанной операции
/users/{userid}/address:
parameters:
- name: userid
in: path
required: true
description: идентификатор пользователя, как userId
schema:
type: string
# связанная операция
get:
operationId: getUserAddress
responses:
'200':
description: адрес пользователя
Когда выражение времени выполнения не может быть вычислено, значение параметра не передается целевой операции.
Значения из тела ответа могут использоваться для управления связанной операцией.
links:
address:
operationId: getUserAddressByUUID
parameters:
# получить поле `uuid` из поля `uuid` в теле ответа
userUuid: $response.body#/uuid
Клиенты следуют всем ссылкам по своему усмотрению. Наличие отношения не гарантирует ни разрешения, ни возможности успешного вызова этой ссылки.
Примеры
использования operationRef
Так как ссылки на operationId
МОГУТ отсутствовать (поле operationId
является необязательным в Объекте операции (Operation Object)), ссылки также могут быть созданы с использованием относительной ссылки operationRef
:
links:
UserRepositories:
# возвращает массив '#/components/schemas/repository'
operationRef: '#/paths/~12.0~1repositories~1{username}/get'
parameters:
username: $response.body#/username
или абсолютной ссылки operationRef
:
links:
UserRepositories:
# возвращает массив '#/components/schemas/repository'
operationRef: 'https://na2.gigantic-server.com/#/paths/~12.0~1repositories~1{username}/get'
parameters:
username: $response.body#/username
Обратите внимание, что при использовании operationRef
требуется экранированный слеш вперед при использовании JSON-ссылок.
Выражения времени выполнения
Выражения времени выполнения позволяют определить значения на основе информации, которая будет доступна только внутри HTTP-сообщения при фактическом вызове API. Этот механизм используется в Объектах Link (Link Objects) и Объектах Callback (Callback Objects).
Выражение времени выполнения определяется следующим синтаксисом ABNF:
expression = ( "$url" / "$method" / "$statusCode" / "$request." source / "$response." source )
source = ( header-reference / query-reference / path-reference / body-reference )
header-reference = "header." token
query-reference = "query." name
path-reference = "path." name
body-reference = "body" ["#" json-pointer ]
json-pointer = *( "/" reference-token )
reference-token = *( unescaped / escaped )
unescaped = %x00-2E / %x30-7D / %x7F-10FFFF
; %x2F ('/') and %x7E ('~') are excluded from 'unescaped'
escaped = "~" ( "0" / "1" )
; representing '~' and '/', respectively
name = *( CHAR )
token = 1*tchar
tchar = "!" / "#" / "$" / "%" / "&" / "'" / "*" / "+" / "-" / "." /
"^" / "_" / "`" / "|" / "~" / DIGIT / ALPHA
Здесь json-pointer
взят из RFC6901, char
из RFC7159 и token
из RFC7230.
Идентификатор name
чувствителен к регистру, тогда как token
- нет.
В таблице ниже приведены примеры выражений времени выполнения и примеры их использования в значении:
Примеры
Местоположение | Пример выражения | Примечания ---|:---|:---| HTTP-метод | $method
| Допустимые значения $method
будут соответствовать HTTP-операции. Запрашиваемый тип медиа | $request.header.accept
|
Параметр запроса | $request.path.id
| Параметры запроса ДОЛЖНЫ быть объявлены в разделе parameters
родительской операции, иначе они не могут быть вычислены. Это также относится к заголовкам запроса. Свойство тела запроса | $request.body#/user/uuid
| В операциях, принимающих тела запросов, можно ссылаться на части requestBody
или на всё тело запроса. URL запроса | $url
|
Значение ответа | $response.body#/status
| В операциях, возвращающих тела ответов, можно ссылаться на части тела ответа или на всё тело ответа. Заголовок ответа | $response.header.Server
| Доступны только отдельные значения заголовка
Выражения времени выполнения сохраняют тип значения, на которое ссылается выражение. Выражения могут быть вставлены в строковые значения, обрамив выражение в фигурные скобки {}
.
Объект Header
Объект Header следует структуре Объекта параметра (Parameter Object) со следующими изменениями:
- Поле
name
НЕ ДОЛЖНО быть указано, оно задается в соответствующем объектеheaders
. - Поле
in
НЕ ДОЛЖНО быть указано, оно неявно принимается равнымheader
. - Все свойства, зависящие от местоположения, ДОЛЖНЫ быть применимы к местоположению
header
(например,style
).
Пример объекта Header
Простой заголовок типа integer
:
{
"description": "Количество разрешенных запросов в текущем периоде",
"schema": {
"type": "integer"
}
}
Объект Tag
Добавляет метаданные для одного тега, который используется в Объекте операции (Operation Object). Не обязательно иметь объект Tag для каждого тега, определенного в экземплярах объекта Operation.
Фиксированные поля
Название поля | Тип | Описание |
---|---|---|
name | string | ОБЯЗАТЕЛЬНО. Название тега. |
description | string | Описание тега. Допускается использование форматирования CommonMark для представления форматированного текста. |
externalDocs | Объект внешней документации (External Documentation Object) | Дополнительная внешняя документация для этого тега. |
Этот объект может быть расширен с помощью Расширений спецификации.
Пример объекта Tag
Объект Reference
Простой объект, позволяющий ссылаться на другие компоненты в документе OpenAPI, как внутренние, так и внешние.
Строковое значение $ref
содержит URI RFC3986, который определяет местоположение ссылки на значение.
См. правила для разрешения Относительных ссылок.
Фиксированные поля
Название поля | Тип | Описание |
---|---|---|
$ref | string | ОБЯЗАТЕЛЬНО. Идентификатор ссылки. Он ДОЛЖЕН быть в форме URI. |
summary | string | Краткое описание, которое по умолчанию ДОЛЖНО переопределять описание ссылочного компонента. Если у ссылочного типа объекта нет поля summary , то это поле не имеет эффекта. |
description | string | Описание, которое по умолчанию ДОЛЖНО переопределять описание ссылочного компонента. Допускается использование форматирования CommonMark для представления форматированного текста. Если у ссылочного типа объекта нет поля description , то это поле не имеет эффекта. |
В этот объект нельзя добавлять дополнительные свойства, и любые добавленные свойства ДОЛЖНЫ быть проигнорированы.
Обратите внимание, что это ограничение на дополнительные свойства является различием между объектами Reference и Объектами схемы
, содержащими ключевое слово $ref
.
Пример объекта Reference
Пример относительного документа схемы
Пример документов с встроенной схемой
Объект Schema
Объект Schema позволяет определить типы входных и выходных данных. Эти типы могут быть объектами, примитивами и массивами. Этот объект является расширением Спецификации схемы JSON.
Дополнительную информацию о свойствах смотрите в разделе Основы схемы JSON и Проверка схемы JSON.
За исключением указания обратного, определения свойств следуют определениям JSON Schema и не добавляют дополнительную семантику. Если JSON Schema указывает, что поведение определяется приложением (например, для аннотаций), то OAS также переносит определение семантики на приложение, использующее документ OpenAPI.
Свойства
Диалект объекта Schema в OpenAPI определяется требованием к основному словарю OAS в дополнение к словарям, определенным в проекте JSON Schema версии 2020-12.
Диалект объекта Schema в OpenAPI для данной версии спецификации идентифицируется URI https://spec.openapis.org/oas/3.1/dialect/base
(идентификатор схемы "диалекта OAS").
Следующие свойства взяты из спецификации JSON Schema, но их определения расширены OAS:
- description - Допускается использование форматирования CommonMark для представления форматированного текста.
- format - Смотрите Форматы данных для получения дополнительных сведений. При полагании на определенные форматы JSON Schema OAS предлагает несколько дополнительных предопределенных форматов.
Помимо свойств JSON Schema, составляющих диалект OAS, объект Schema поддерживает ключевые слова из любых других словарей или полностью произвольные свойства.
Основной словарь OpenAPI Specification состоит из следующих ключевых слов:
Фиксированные поля
Название поля | Тип | Описание |
---|---|---|
discriminator | Объект дискриминатора (Discriminator Object) | Добавляет поддержку полиморфизма. Дискриминатор - это имя объекта, которое используется для различения между другими схемами, которые могут удовлетворять описанию полезной нагрузки. См. Композицию и наследование для получения дополнительных сведений. |
xml | Объект XML (XML Object) | Может использоваться только схемами свойств. Не оказывает влияния на корневые схемы. Добавляет дополнительные метаданные для описания XML-представления этого свойства. |
externalDocs | Объект внешней документации (External Documentation Object) | Дополнительная внешняя документация для этой схемы. |
example | Любой | Свободное свойство для включения примера экземпляра для этой схемы. Для представления примеров, которые нельзя естественным образом представить в формате JSON или YAML, можно использовать строковое значение, содержащее пример с необходимым экранированием. Устарело: Свойство example было устаревшим и заменено ключевым словом JSON Schema examples . Использование свойства example не рекомендуется, и последующие версии этой спецификации могут его удалить. |
Этот объект может быть расширен с помощью Расширений спецификации, хотя, как уже отмечалось, дополнительные свойства могут опускать префикс x-
внутри этого объекта.
Композиция и наследование (полиморфизм)
Спецификация OpenAPI позволяет объединять и расширять определения моделей с помощью свойства allOf
из JSON Schema, фактически предлагая композицию моделей. allOf
принимает массив определений объектов, которые проверяются независимо, но вместе составляют один объект.
Хотя композиция обеспечивает расширяемость модели, она не подразумевает иерархию между моделями. Для поддержки полиморфизма спецификация OpenAPI добавляет поле discriminator
. При его использовании discriminator
будет именем свойства, определяющим, какое определение схемы проверяет структуру модели. Таким образом, поле discriminator
ДОЛЖНО быть обязательным полем. Существуют два способа определения значения дискриминатора для экземпляра наследуемой модели: - Использовать имя схемы. - Переопределить имя схемы новым значением. Если новое значение существует, оно имеет приоритет над именем схемы. Таким образом, встроенные определения схемы, у которых нет заданного идентификатора, не могут использоваться при полиморфизме.
XML Моделирование
Свойство xml позволяет задавать дополнительные определения при переводе JSON-определения в XML. Объект XML содержит дополнительную информацию о доступных параметрах.
Спецификация схем
Важно, чтобы инструментарий мог определить, с помощью какого диалекта или мета-схемы следует обрабатывать конкретный ресурс: JSON Schema Core, JSON Schema Validation, диалект схем OpenAPI или некоторая пользовательская мета-схема.
Ключевое слово $schema
МОЖЕТ присутствовать в любом объекте Schema Object корневого уровня и, если оно присутствует, ОБЯЗАТЕЛЬНО должно использоваться для определения того, какой диалект следует использовать при обработке схемы. Это позволяет использовать Schema Objects, соответствующие другим версиям черновика JSON Schema, чем поддерживаемый по умолчанию Draft 2020-12. Инструментарий ДОЛЖЕН поддерживать идентификатор схемы диалекта OAS и МОЖЕТ поддерживать дополнительные значения $schema
.
Чтобы разрешить использование другого значения $schema
по умолчанию для всех Schema Objects, содержащихся в документе OAS, может быть установлено значение jsonSchemaDialect
внутри объекта OpenAPI. Если это значение по умолчанию не задано, то для этих Schema Objects ДОЛЖЕН использоваться идентификатор схемы диалекта OAS. Значение $schema
внутри объекта Schema всегда переопределяет любое значение по умолчанию.
Когда Schema Object ссылается на внешний ресурс, который не является документом OAS (например, простой ресурс JSON Schema), значение ключевого слова $schema
для схем в этом ресурсе ДОЛЖНО соответствовать правилам JSON Schema.
Примеры объекта Schema
Пример примитивного типа
Пример простой модели
{
"type": "object",
"required": [
"name"
],
"properties": {
"name": {
"type": "string"
},
"address": {
"$ref": "#/components/schemas/Address"
},
"age": {
"type": "integer",
"format": "int32",
"minimum": 0
}
}
}
type: object
required:
- name
properties:
name:
type: string
address:
$ref: '#/components/schemas/Address'
age:
type: integer
format: int32
minimum: 0
Пример модели с свойствами типа "map"/"dictionary"
Для простого отображения строки на строку:
Для отображения строки на модель:
Пример модели с примером
{
"type": "object",
"properties": {
"id": {
"type": "integer",
"format": "int64"
},
"name": {
"type": "string"
}
},
"required": [
"name"
],
"example": {
"name": "Puma",
"id": 1
}
}
type: object
properties:
id:
type: integer
format: int64
name:
type: string
required:
- name
example:
name: Puma
id: 1
Пример модели с композицией
{
"components": {
"schemas": {
"ErrorModel": {
"type": "object",
"required": [
"message",
"code"
],
"properties": {
"message": {
"type": "string"
},
"code": {
"type": "integer",
"minimum": 100,
"maximum": 600
}
}
},
"ExtendedErrorModel": {
"allOf": [
{
"$ref": "#/components/schemas/ErrorModel"
},
{
"type": "object",
"required": [
"rootCause"
],
"properties": {
"rootCause": {
"type": "string"
}
}
}
]
}
}
}
}
components:
schemas:
ErrorModel:
type: object
required:
- message
- code
properties:
message:
type: string
code:
type: integer
minimum: 100
maximum: 600
ExtendedErrorModel:
allOf:
- $ref: '#/components/schemas/ErrorModel'
- type: object
required:
- rootCause
properties:
rootCause:
type: string
Пример модели с поддержкой полиморфизма
{
"components": {
"schemas": {
"Pet": {
"type": "object",
"discriminator": {
"propertyName": "petType"
},
"properties": {
"name": {
"type": "string"
},
"petType": {
"type": "string"
}
},
"required": [
"name",
"petType"
]
},
"Cat": {
"description": "A representation of a cat. Note that `Cat` will be used as the discriminator value.",
"allOf": [
{
"$ref": "#/components/schemas/Pet"
},
{
"type": "object",
"properties": {
"huntingSkill": {
"type": "string",
"description": "The measured skill for hunting",
"default": "lazy",
"enum": [
"clueless",
"lazy",
"adventurous",
"aggressive"
]
}
},
"required": [
"huntingSkill"
]
}
]
},
"Dog": {
"description": "A representation of a dog. Note that `Dog` will be used as the discriminator value.",
"allOf": [
{
"$ref": "#/components/schemas/Pet"
},
{
"type": "object",
"properties": {
"packSize": {
"type": "integer",
"format": "int32",
"description": "the size of the pack the dog is from",
"default": 0,
"minimum": 0
}
},
"required": [
"packSize"
]
}
]
}
}
}
}
components:
schemas:
Pet:
type: object
discriminator:
propertyName: petType
properties:
name:
type: string
petType:
type: string
required:
- name
- petType
Cat: ## "Cat" will be used as the discriminator value
description: A representation of a cat
allOf:
- $ref: '#/components/schemas/Pet'
- type: object
properties:
huntingSkill:
type: string
description: The measured skill for hunting
enum:
- clueless
- lazy
- adventurous
- aggressive
required:
- huntingSkill
Dog: ## "Dog" will be used as the discriminator value
description: A representation of a dog
allOf:
- $ref: '#/components/schemas/Pet'
- type: object
properties:
packSize:
type: integer
format: int32
description: the size of the pack the dog is from
default: 0
minimum: 0
required:
- packSize
Объект дискриминатора
Когда тела запросов или ответы могут соответствовать различным схемам, объект discriminator
может быть использован для помощи в сериализации, десериализации и валидации. Дискриминатор - это конкретный объект в схеме, который используется для информирования получателя документа об альтернативной схеме на основе связанного с ним значением.
При использовании дискриминатора встроенные схемы не учитываются.
Фиксированные поля
Этот объект МОЖЕТ быть расширен с помощью Расширений спецификации.
Объект дискриминатора является допустимым только при использовании одного из составных ключевых слов oneOf
, anyOf
, allOf
.
В OAS 3.0 ответные данные МОГУТ быть описаны как один из нескольких типов:
MyResponseType:
oneOf:
- $ref: '#/components/schemas/Cat'
- $ref: '#/components/schemas/Dog'
- $ref: '#/components/schemas/Lizard'
что означает, что ответные данные ДОЛЖНЫ, согласно валидации, соответствовать только одной из схем, описанных в Cat
, Dog
или Lizard
. В этом случае дискриминатор МОЖЕТ действовать как "подсказка" для упрощения валидации и выбора соответствующей схемы, что может быть затратной операцией в зависимости от сложности схемы. Таким образом, можно точно указать, какое поле сообщает нам, какую схему использовать:
MyResponseType:
oneOf:
- $ref: '#/components/schemas/Cat'
- $ref: '#/components/schemas/Dog'
- $ref: '#/components/schemas/Lizard'
discriminator:
propertyName: petType
Ожидается, что свойство с именем petType
ДОЛЖНО присутствовать в ответных данных, и его значение будет соответствовать имени схемы, определенной в документе OAS. Таким образом, ответные данные:
Укажут, что должна использоваться схема Cat
с этими данными.
В случаях, когда значение дискриминатора не совпадает с именем схемы или невозможно определить неявное сопоставление, можно использовать необязательное определение mapping
:
MyResponseType:
oneOf:
- $ref: '#/components/schemas/Cat'
- $ref: '#/components/schemas/Dog'
- $ref: '#/components/schemas/Lizard'
- $ref: 'https://gigantic-server.com/schemas/Monster/schema.json'
discriminator:
propertyName: petType
mapping:
dog: '#/components/schemas/Dog'
monster: 'https://gigantic-server.com/schemas/Monster/schema.json'
Здесь значение дискриминатора dog
будет сопоставлено с схемой #/components/schemas/Dog
, а не с значением Dog
по умолчанию (неявным). Если значение дискриминатора не соответствует неявному или явному сопоставлению, невозможно определить схему, и валидация ДОЛЖНА завершиться неудачей. Ключи сопоставления ДОЛЖНЫ быть строковыми значениями, но инструментарий МОЖЕТ преобразовывать значения из ответа в строки для сравнения.
При использовании в связке с конструкцией anyOf
дискриминатор может избежать неоднозначности, когда несколько схем могут соответствовать единственным данным.
В обоих случаях использования oneOf
и anyOf
все возможные схемы ДОЛЖНЫ быть перечислены явно. Чтобы избежать избыточности, дискриминатор может быть добавлен в определение родительской схемы, и все схемы, входящие в родительскую схему в конструкции allOf
, могут быть использованы в качестве альтернативной схемы.
Например:
components:
schemas:
Pet:
type: object
required:
- petType
properties:
petType:
type: string
discriminator:
propertyName: petType
mapping:
dog: Dog
Cat:
allOf:
- $ref: '#/components/schemas/Pet'
- type: object
# все другие свойства, характерные для `Cat`
properties:
name:
type: string
Dog:
allOf:
- $ref: '#/components/schemas/Pet'
- type: object
# все другие свойства, х
арактерные для `Dog`
properties:
bark:
type: string
Lizard:
allOf:
- $ref: '#/components/schemas/Pet'
- type: object
# все другие свойства, характерные для `Lizard`
properties:
lovesRocks:
type: boolean
данные ответа, подобные этим:
будут указывать на использование схемы Cat
. Аналогично этой схеме:
будет соответствовать схеме Dog
из-за определения в элементе mapping
.
Объект Security Scheme (Схема безопасности)
Определяет схему безопасности, которая может использоваться операциями.
Поддерживаемые схемы включают HTTP-аутентификацию, API-ключ (в виде заголовка, параметра cookie или параметра запроса), взаимную аутентификацию по TLS (использование клиентского сертификата), распространенные потоки OAuth2 (неявный, пароль, учетные данные клиента и авторизационный код), определенные в RFC6749, а также OpenID Connect Discovery. Обратите внимание, что с 2020 года неявный поток будет устаревать согласно Наилучшей практике по безопасности OAuth 2.0. Рекомендуется использовать поток авторизации с кодом и проверкой PKCE для большинства случаев использования.
Фиксированные поля
Название поля | Тип | Применяется к | Описание |
---|---|---|---|
type | string | Любой | ОБЯЗАТЕЛЬНО. Тип схемы безопасности. Допустимые значения: "apiKey" , "http" , "mutualTLS" , "oauth2" , "openIdConnect" . |
description | string | Любой | Описание схемы безопасности. Может использоваться синтаксис CommonMark для отображения форматированного текста. |
name | string | apiKey | ОБЯЗАТЕЛЬНО. Имя заголовка, параметра запроса или параметра cookie, которое будет использоваться. |
in | string | apiKey | ОБЯЗАТЕЛЬНО. Местоположение API-ключа. Допустимые значения: "query" , "header" или "cookie" . |
scheme | string | http | ОБЯЗАТЕЛЬНО. Имя схемы авторизации HTTP, которая будет использоваться в заголовке Authorization, как определено в RFC7235. Используемые значения РЕКОМЕНДУЕТСЯ зарегистрировать в реестре аутентификационных схем IANA. |
bearerFormat | string | http ("bearer" ) | Подсказка клиенту о форматировании маркера авторизации. Маркеры авторизации обычно генерируются сервером авторизации, поэтому эта информация в основном предназначена для документации. |
flows | Объект OAuth Flows | oauth2 | ОБЯЗАТЕЛЬНО. Объект, содержащий информацию о конфигурации поддерживаемых типов потоков. |
openIdConnectUrl | string | openIdConnect | ОБЯЗАТЕЛЬНО. URL OpenID Connect для обнаружения значений конфигурации OAuth2. Должен быть в формате URL. Стандарт OpenID Connect требует использования TLS. |
В этот объект МОЖНО добавлять расширения спецификации.
Пример объекта Security Scheme
Пример базовой аутентификации
Пример использования API-ключа
Пример использования маркера JWT Bearer
Пример неявного потока OAuth2
{
"type": "oauth2",
"flows": {
"implicit": {
"authorizationUrl": "https://example.com/api/oauth/dialog",
"scopes": {
"write:pets": "изменение питомцев в вашей учетной записи",
"read:pets": "чтение ваших питомцев"
}
}
}
}
type: oauth2
flows:
implicit:
authorizationUrl: https://example.com/api/oauth/dialog
scopes:
write:pets: изменение питомцев в вашей учетной записи
read:pets: чтение ваших питомцев
Объект OAuth Flows (Потоки OAuth)
Позволяет настраивать поддерживаемые потоки OAuth.
Фиксированные поля
Название поля | Тип | Описание |
---|---|---|
implicit | Объект OAuth Flow | Конфигурация для неявного потока OAuth |
password | Объект OAuth Flow | Конфигурация для потока ресурсов с владельцем пароля OAuth |
clientCredentials | Объект OAuth Flow | Конфигурация для потока учетных данных клиента OAuth. Ранее назывался application в OpenAPI 2.0. |
authorizationCode | Объект OAuth Flow | Конфигурация для потока авторизации с кодом OAuth. Ранее назывался accessCode в OpenAPI 2.0. |
В этот объект МОЖНО добавлять расширения спецификации.
Объект OAuth Flow (Поток OAuth)
Предоставляет конфигурационные данные для поддерживаемого потока OAuth.
Фиксированные поля
В этот объект МОЖНО добавлять расширения спецификации.
Примеры объекта OAuth Flow
{
"type": "oauth2",
"flows": {
"implicit": {
"authorizationUrl": "https://example.com/api/oauth/dialog",
"scopes": {
"write:pets": "изменение питомцев в вашей учетной записи",
"read:pets": "чтение ваших питомцев"
}
},
"authorizationCode": {
"authorizationUrl": "https://example.com/api/oauth/dialog",
"tokenUrl": "https://example.com/api/oauth/token",
"scopes": {
"write:pets": "изменение питомцев в вашей учетной записи",
"read:pets": "чтение ваших питомцев"
}
}
}
}
type: oauth2
flows:
implicit:
authorizationUrl: https://example.com/api/oauth/dialog
scopes:
write:pets: изменение питомцев в вашей учетной записи
read:pets: чтение ваших питомцев
authorizationCode:
authorizationUrl: https://example.com/api/oauth/dialog
tokenUrl: https://example.com/api/oauth/token
scopes:
write:pets: изменение питомцев в вашей учетной записи
read:pets: чтение ваших питомцев
Объект Security Requirement (Требование безопасности)
Список требуемых схем безопасности для выполнения этой операции. Имя, используемое для каждого свойства, ДОЛЖНО соответствовать схеме безопасности, объявленной в Security Schemes внутри Components Object.
Объекты Security Requirement, содержащие несколько схем, требуют, чтобы все схемы были выполнены для авторизации запроса. Это позволяет поддерживать сценарии, когда для передачи информации о безопасности требуется несколько параметров запроса или заголовков HTTP.
Когда список объектов Security Requirement определен в OpenAPI Object или Operation Object, достаточно выполнения одного из объектов Security Requirement в списке для авторизации запроса.
Шаблонные поля
Шаблон поля | Тип | Описание |
---|---|---|
{name} | [string ] | Каждое имя ДОЛЖНО соответствовать схеме безопасности, которая объявлена в Security Schemes внутри Components Object. Если схема безопасности имеет тип "oauth2" или "openIdConnect" , то значение представляет собой список требуемых областей для выполнения, и список МОЖЕТ быть пустым, если авторизация не требует указанной области. Для других типов схем безопасности массив МОЖЕТ содержать список требуемых ролей для выполнения, которые в противном случае не определены или не передаются встроенным способом. |
Примеры объекта Security Requirement
Требование безопасности без использования OAuth2
Требование безопасности OAuth2
Дополнительная безопасность OAuth2
Дополнительная безопасность OAuth2, как определено в OpenAPI Object или Operation Object:
Расширения спецификации
Хотя спецификация OpenAPI пытается удовлетворить большинство случаев использования, дополнительные данные могут быть добавлены для расширения спецификации в определенных точках.
Свойства расширений реализованы как поля с шаблонными именами, которые всегда начинаются с префикса "x-"
.
Шаблон поля | Тип | Описание |
---|---|---|
^x- | Любой | Позволяет добавлять расширения в схему OpenAPI. Имя поля ДОЛЖНО начинаться с x- , например, x-internal-id . Имена полей, начинающиеся с x-oai- и x-oas- , зарезервированы для использования, определенного OpenAPI Initiative. Значение может быть null , примитивом, массивом или объектом. |
Расширения могут быть поддержаны или не поддержаны используемыми инструментами, но они также могут быть расширены для добавления требуемой поддержки (если инструменты являются внутренними или с открытым исходным кодом).
Фильтрация безопасности
Некоторые объекты в спецификации OpenAPI МОГУТ быть объявлены и оставаться пустыми или полностью удалены, даже если они являются неотъемлемой частью документации API.
Причина этого состоит в том, чтобы предоставить дополнительный уровень контроля доступа к документации. Хотя это не является частью самой спецификации, некоторые библиотеки МОГУТ позволить доступ к частям документации на основе некоторой формы аутентификации/авторизации.
Вот два примера:
- Объект Paths Object МОЖЕТ присутствовать, но быть пустым. Это может показаться противоречивым, но это может сообщить пользователю, что он попал в нужное место, но не имеет доступа к документации. Пользователь все равно будет иметь доступ по крайней мере к Info Object, который может содержать дополнительную информацию о проверке подлинности.
- Объект Path Item Object МОЖЕТ быть пустым. В этом случае пользователь будет знать о наличии пути, но не сможет увидеть его операции или параметры. Это отличается от скрытия самого пути в Paths Object, потому что пользователь будет знать о его существовании. Это позволяет поставщику документации тонко управлять тем, что пользователь может видеть.
Приложение А: История изменений
Версия | Дата | Примечания |
---|---|---|
3.1.0 | 2021-02-15 | Выпуск спецификации OpenAPI 3.1.0 |
3.1.0-rc1 | 2020-10-08 | rc1 спецификации 3.1 |
3.1.0-rc0 | 2020-06-18 | rc0 спецификации 3.1 |
3.0.3 | 2020-02-20 | Патч-релиз спецификации OpenAPI 3.0.3 |
3.0.2 | 2018-10-08 | Патч-релиз спецификации OpenAPI 3.0.2 |
3.0.1 | 2017-12-06 | Патч-релиз спецификации OpenAPI 3.0.1 |
3.0.0 | 2017-07-26 | Выпуск спецификации OpenAPI 3.0.0 |
3.0.0-rc2 | 2017-06-16 | rc2 спецификации 3.0 |
3.0.0-rc1 | 2017-04-27 | rc1 спецификации 3.0 |
3.0.0-rc0 | 2017-02-28 | Рабочий черновик спецификации 3.0 |
2.0 | 2015-12-31 | Пожертвование Swagger 2.0 в OpenAPI Initiative |
2.0 | 2014-09-08 | Выпуск Swagger 2.0 |
1.2 | 2014-03-14 | Первоначальный выпуск формального документа. |
1.1 | 2012-08-22 | Выпуск Swagger 1.1 |
1.0 | 2011-08-10 | Первый выпуск спецификации Swagger |