Спецификация 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, инструментами для генерации кода для создания серверов и клиентов на различных языках программирования, инструментами для тестирования и многими другими случаями использования.

Содержание

• Определения
  • Документ OpenAPI
  • Шаблонизация пути
  • Типы медиа
  • Коды состояния HTTP
• Спецификация
  • Версии
  • Формат
  • Структура документа
  • Типы данных
  • Форматирование текста
  • Относительные ссылки в 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:

{
   "field": [ 1, 2, 3 ]
}

Схема предоставляет два типа полей: фиксированные поля с объявленным именем и поля по шаблону, которые объявляют регулярное выражение для имени поля.

Поля по шаблону ДОЛЖНЫ иметь уникальные имена внутри содержащего объекта.

Для сохранения возможности обратного преобразования между форматами 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:

Форматирование текста с использованием разметки

Во всей спецификации поля 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.

Фиксированные поля

Этот объект МОЖЕТ быть расширен с помощью Расширений Спецификации.

Объект Info

Объект предоставляет метаданные об 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"
}

name: Поддержка API
url: https://www.example.com/support
email: support@example.com

Объект License (Лицензия)

Информация о лицензии для открытого API.

Фиксированные поля

Этот объект МОЖЕТ быть расширен с помощью Расширений Спецификации.

Пример объекта License (Лицензия)

{
  "name": "Apache 2.0",
  "identifier": "Apache-2.0"
}

name: Apache 2.0
identifier: Apache-2.0

Объект Server (Сервер)

Объект, представляющий сервер.

Фиксированные поля

Этот объект МОЖЕТ быть расширен с помощью Расширений Спецификации.

Пример объекта Server (Сервер)

Описание одного сервера:

{
  "url": "https://development.gigantic-server.com/v1",
  "description": "Development server"
}

url: https://development.gigantic-server.com/v1
description: Development 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-шаблон сервера.

Фиксированные поля

Этот объект МОЖЕТ быть расширен с помощью Расширений Спецификации.

Объект Сomponents (Компоненты)

Содержит набор повторно используемых объектов для различных аспектов OAS. Все объекты, определенные внутри объекта компонентов, не будут иметь эффекта на API, если они явно не будут ссылаться извне объекта компонентов.

Фиксированные поля

Этот объект МОЖЕТ быть расширен с помощью Расширений Спецификации.

Все фиксированные поля, указанные выше, являются объектами, которые ДОЛЖНЫ использовать ключи, соответствующие регулярному выражению: ^[a-zA-Z0-9\.\-_]+$.

Примеры Имен Полей:

User
User_1
User_Name
user-name
my.org.User

Пример объекта 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).

Поля с шаблоном

Объект может быть расширен с помощью расширений спецификации.

Сопоставление шаблонов пути

Предположим, что имеются следующие пути, то конкретное определение /pets/mine будет сопоставлено первым, если будет использовано:

  /pets/{petId}
  /pets/mine

Следующие пути считаются идентичными и недопустимыми:

  /pets/{petId}
  /pets/{name}

Следующее может привести к неоднозначному разрешению:

  /{entity}/me
  /books/{id}

Пример объекта 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). Сам путь все равно отображается во вьюере документации, но они не будут знать, какие операции и параметры доступны.

Фиксированные поля

Объект может быть расширен с помощью расширений спецификации.

Объект Operation (Операции)

Описывает одну операцию API для пути.

Фиксированные поля

Этот объект МОЖЕТ быть расширен с помощью расширений спецификации.

Пример объекта 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 (Внешняя документация)

Позволяет ссылаться на внешний ресурс для расширенной документации.

Фиксированные поля

Этот объект МОЖЕТ быть расширен с помощью расширений спецификации.

Пример объекта externalDocumentation (внешней документации)

{
  "description": "Найти больше информации здесь",
  "url": "https://example.com"
}

description: Найти больше информации здесь
url: https://example.com

Объект Parameter (Параметр)

Описывает отдельный параметр операции.

Уникальный параметр определяется комбинацией имени и местоположения параметра.

Местоположения параметра

Местоположение параметра определяется полем in и может иметь четыре возможных значения: * path - используется вместе с шаблонами пути, где значение параметра фактически является частью URL операции. Это не включает хост или базовый путь API. Например, в /items/{itemId} параметр пути - это itemId. * query - параметры, добавляемые в URL. Например, в /items?id=### параметр запроса - это id. * header - пользовательские заголовки, ожидаемые как часть запроса. Обратите внимание, что имена заголовков нечувствительны к регистру, согласно RFC7230. * cookie - используется для передачи конкретного значения cookie в API.

Фиксированные поля

Правила сериализации параметра определяются двумя способами. Для простых сценариев схема и стиль могут описывать структуру и синтаксис значения параметра.

Для более сложных сценариев свойство content может определять тип медиа и схему параметра. Параметр ДОЛЖЕН содержать либо свойство schema, либо свойство content, но не оба сразу. Когда предоставляются example или examples вместе с объектом schema, пример ДОЛЖЕН следовать предписанной стратегии сериализации параметра.

Значения стиля

Для поддержки обычных способов сериализации простых параметров определен набор значений style.

Примеры стиля

Предположим, что параметр с именем color имеет одно из следующих значений:

   string -> "blue"
   array -> ["blue","black","brown"]
   object -> { "R": 100, "G": 200, "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"
}

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

Описывает единственное тело запроса.

Фиксированные поля

Этот объект может быть расширен с помощью расширений спецификации.

Примеры объекта 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 предоставляет схему и примеры для типа медиа, определенного по ключу.

Фиксированные поля

Этот объект может быть расширен с помощью расширений спецификации.

Примеры типа медиа

{
  "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:

# изображение PNG в бинарном файле:
content:
    image/png: {}

# произвольный бинарный файл:
content:
    application/octet-stream: {}

Бинарное содержимое, передаваемое с использованием кодирования base64:

content:
    image/png:
        schema:
            type: string
            contentMediaType: image/png
            contentEncoding: base64

Обратите внимание, что Content-Type остается image/png, описывая семантику полезной нагрузки. Свойства JSON Schema type и contentEncoding объясняют, что полезная нагрузка передается в виде текста. Ключевое слово contentMediaType JSON Schema технически избыточно, но может быть использовано инструментами JSON Schema, которые могут не знать о контексте OpenAPI.

Эти примеры применяются как к входным данным файлового ввода, так и к выходным данным.

Пример requestBody для отправки файла в операции POST может выглядеть следующим образом:

requestBody:
  content:
    application/octet-stream: {}

Кроме того, можно указать конкретные типы медиа:

# можно указать несколько конкретных типов медиа:
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)

Описание кодирования, применяемого к конкретному свойству схемы.

Фиксированные поля

Этот объект МОЖЕТ быть расширен с помощью Расширений спецификации (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 ДОЛЖЕН содержать как минимум один код ответа, и если предоставлен только один код ответа, то ЭТО ДОЛЖЕН быть ответ на успешный вызов операции.

Поля по шаблону

Этот объект МОЖЕТ быть расширен с помощью Расширений спецификации (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 к операциям на основе ответа.

Фиксированные поля

Этот объект МОЖЕТ быть расширен с помощью Расширений спецификации (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

Ответ в виде простого текста с заголовками:

{
  "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

Ответ без значения возврата:

{
  "description": "создан объект"
}

description: создан объект

Объект Callback

Словарь возможных асинхронных вызовов, связанных с родительской операцией. Каждое значение в словаре - это Объект элемента пути (Path Item Object), описывающий набор запросов, которые могут быть инициированы провайдером API, и ожидаемые ответы. Значение ключа, используемое для идентификации объекта элемента пути, представляет собой выражение, вычисляемое во время выполнения, которое идентифицирует URL, используемый для запроса обратного вызова.

Для описания входящих запросов от провайдера API независимо от другого вызова API используйте поле webhooks.

Поля с шаблонами

Этот объект МОЖЕТ быть расширен с помощью Расширений спецификации (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.

Примеры объекта 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

Объект Примера

Фиксированные поля

Этот объект МОЖЕТ быть расширен с помощью Расширений спецификации (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 не требует наличия информации о ссылке в ответе во время выполнения.

Для вычисления ссылок и предоставления инструкций по их выполнению используется выражение времени выполнения, которое позволяет получить доступ к значениям операции и использовать их в качестве параметров при вызове связанной операции.

Фиксированные поля

Этот объект МОЖЕТ быть расширен с помощью Расширений спецификации (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) со следующими изменениями:

1. Поле name НЕ ДОЛЖНО быть указано, оно задается в соответствующем объекте headers.
2. Поле in НЕ ДОЛЖНО быть указано, оно неявно принимается равным header.
3. Все свойства, зависящие от местоположения, ДОЛЖНЫ быть применимы к местоположению header (например, style).

Пример объекта Header

Простой заголовок типа integer:

{
  "description": "Количество разрешенных запросов в текущем периоде",
  "schema": {
    "type": "integer"
  }
}

description: Количество разрешенных запросов в текущем периоде
schema:
  type: integer

Объект Tag

Добавляет метаданные для одного тега, который используется в Объекте операции (Operation Object). Не обязательно иметь объект Tag для каждого тега, определенного в экземплярах объекта Operation.

Фиксированные поля

Этот объект может быть расширен с помощью Расширений спецификации.

Пример объекта Tag

{
    "name": "pet",
    "description": "Операции с животными"
}

name: pet
description: Операции с животными

Объект Reference

Простой объект, позволяющий ссылаться на другие компоненты в документе OpenAPI, как внутренние, так и внешние.

Строковое значение $ref содержит URI RFC3986, который определяет местоположение ссылки на значение.

См. правила для разрешения Относительных ссылок.

Фиксированные поля

В этот объект нельзя добавлять дополнительные свойства, и любые добавленные свойства ДОЛЖНЫ быть проигнорированы.

Обратите внимание, что это ограничение на дополнительные свойства является различием между объектами Reference и Объектами схемы, содержащими ключевое слово $ref.

Пример объекта Reference

{
    "$ref": "#/components/schemas/Pet"
}

$ref: '#/components/schemas/Pet'

Пример относительного документа схемы

{
  "$ref": "Pet.json"
}

$ref: Pet.yaml

Пример документов с встроенной схемой

{
  "$ref": "definitions.json#/Pet"
}

$ref: definitions.yaml#/Pet

Объект 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 состоит из следующих ключевых слов:

Фиксированные поля