Адреса электронной почты организации или внутренней группы используются сотрудниками внутренней организации для доступа к внутренним группам и внутренним функциям, предназначенным для сотрудников. Эти учетные записи могут быть настроены с модерацией для получения электронных писем только от сотрудников организации.

Примеры: 

• [email protected]
• [email protected]
• [email protected]
• [email protected]​

Чтобы создать профессиональный адрес электронной почты с вашим доменом для общих учетных записей или списков рассылки для вашего домена, вам необходимо создать группу электронной почты с публичным доступом. Подробные инструкции по созданию и управлению групповыми учетными записями электронной почты с профессиональными адресами электронной почты в Zoho Mail см. здесь.

Ниже приведены некоторые из наиболее полезных функций при создании учетных записей групп на основе домена в Zoho Mail: 

• Вы можете добавить несколько участников и назначить несколько модераторов для каждой группы.
• Модератор будет иметь права группы и сможет дополнительно добавлять пользователей или изменять настройки этой группы. Модератор также может модерировать электронные письма, отправляемые группе, и одобрять или отклонять их.
• Пользователи могут отправлять электронные письма, используя групповой адрес. Эта функция может быть расширена администратором для всех участников группы или только для определенных участников.
• Когда пользователи отправляют электронные письма, используя групповой адрес электронной почты, их индивидуальный адрес электронной почты не будет виден получателю.
• Администратор может включить функцию «Потоки» для группы, с помощью которой участники группы могут сотрудничать и общаться внутри группы прямо из папки «Входящие».

  Ключевые слова «ДОЛЖЕН», «НЕ ДОЛЖЕН», «ТРЕБУЕТСЯ», «ДОЛЖЕН», «НЕ ДОЛЖЕН», «СЛЕДУЕТ», «НЕ ДОЛЖЕН», «РЕКОМЕНДУЕТСЯ», «НЕ РЕКОМЕНДУЕТСЯ», «МОЖЕТ» и » НЕОБЯЗАТЕЛЬНО» в этом документе следует интерпретировать, как описано в BCP 14 RFC2119. RFC8174, когда и только когда они появляются заглавными буквами, как показано здесь.

  Этот документ находится под лицензией Apache License, Version 2.0.

  Введение

  Спецификация OpenAPI (OAS) определяет стандартный, независимый от языка интерфейс для RESTful API, который позволяет людям и компьютерам обнаруживать и понимать возможности службы без доступа к исходному коду, документации или проверки сетевого трафика. . При правильном определении потребитель может понимать и взаимодействовать с удаленной службой с минимальным количеством логики реализации.

  Затем определение OpenAPI может использоваться инструментами создания документации для отображения API, инструментами генерации кода для создания серверов и клиентов на различных языках программирования, инструментами тестирования и многими другими вариантами использования.

  Содержание

  • Определения
    • Документ OpenAPI
    • Шаблон пути
    • Типы носителей
    • Коды состояния HTTP
  • Спецификация
    • Версии
    • Формат
    • Структура документа
    • Типы данных
    • Расширенное форматирование текста
    • Относительные ссылки в URL-адресах
    • Схема
      • Объект OpenAPI
      • Информационный объект
      • Контакт Объект
      • Объект лицензии
      • Объект сервера
      • Переменный объект сервера
      • Компоненты Объект
      • Пути Объект
      • Объект элемента пути
      • Операционный Объект
      • Объект внешней документации
      • Объект параметров
      • Объект тела запроса
      • Тип носителя Объект
      • Объект кодирования
      • Ответы Объект
      • Объект ответа
      • Объект обратного вызова
      • Пример объекта
      • Объект связи
      • Объект заголовка
      • Объект тега
      • Справочный объект
      • Объект схемы
      • Дискриминатор Объект
      • XML-объект
      • Объект схемы безопасности
      • Объект потоков OAuth
      • Объект потока OAuth
      • Объект требования безопасности
    • Расширения спецификации
    • Фильтрация безопасности
  • Приложение A: История изменений

  Определения

  Документ OpenAPI

  Документ (или набор документов), определяющий или описывающий API. Определение OpenAPI использует спецификацию OpenAPI и соответствует ей.

  Шаблон пути

  Шаблон пути относится к использованию выражений шаблона, разделенных фигурными скобками ({}), для пометки раздела пути URL как заменяемого с использованием параметров пути.

  Каждое выражение шаблона в пути ДОЛЖНО соответствовать параметру пути, который включен в сам элемент пути и/или в каждую из операций элемента пути.

  Типы носителей

  Определения типов носителей распределены по нескольким ресурсам. Определения типа носителя ДОЛЖНЫ соответствовать RFC6838.

  Некоторые примеры возможных определений типа носителя:

   text/plain; кодировка = utf-8
    приложение/json
    приложение/vnd.github+json
    приложение/vnd.github.v3+json
    приложение/vnd.github.v3.raw+json
    приложение/vnd.github.v3.text+json
    приложение/vnd.github.v3.html+json
    приложение/vnd.github.v3.full+json
    приложение /vnd.github.v3.diff
    приложение /vnd.github.v3.patch
   

  Коды состояния HTTP

  Коды состояния HTTP используются для индикации состояния выполняемой операции. Доступные коды состояния определены в RFC7231, а зарегистрированные коды состояния перечислены в реестре кодов состояния IANA.

  Спецификация

  Версии

  Версия спецификации OpenAPI создается с использованием Semantic Versioning 2.0.0 (semver) и соответствует спецификации semver.

  Основной . второстепенная часть семвера (например 3.0 ) ДОЛЖЕН обозначать набор функций OAS. Как правило, в версиях .patch в этом документе рассматриваются ошибки, а не набор функций. Инструменты, поддерживающие OAS 3.0, ДОЛЖНЫ быть совместимы со всеми версиями OAS 3.0.*. Версия исправления НЕ ДОЛЖНА учитываться инструментами, например, не делая различий между 3.0.0 и 3.0.1 .

  Каждая новая дополнительная версия Спецификации OpenAPI ДОЛЖНА позволять любому документу OpenAPI, который действителен по сравнению с любой предыдущей дополнительной версией Спецификации, в пределах той же основной версии быть обновленным до новой версии Спецификации с эквивалентной семантикой. Такое обновление ДОЛЖНО требовать только изменения свойство openapi для новой минорной версии.

  Например, допустимый документ OpenAPI 3.0.2 после изменения его свойства openapi на 3.1.0 ДОЛЖЕН быть действительным документом OpenAPI 3.1.0, семантически эквивалентным исходному документу OpenAPI 3.0.2. Новые второстепенные версии спецификации OpenAPI ДОЛЖНЫ быть написаны, чтобы обеспечить эту форму обратной совместимости.

  Документ OpenAPI, совместимый с OAS 3.*.*, содержит обязательное поле openapi , которое указывает используемую семантическую версию OAS. (Документы OAS 2.0 содержат поле версии верхнего уровня с именем чванство и значение "2.0" .)

  Формат

  Документ OpenAPI, соответствующий спецификации OpenAPI, сам по себе является объектом JSON, который может быть представлен в формате JSON или YAML.

  Например, если поле имеет значение массива, будет использоваться представление массива JSON:

   {
     "поле": [ 1, 2, 3 ]
  }
   

  Все имена полей в спецификации чувствительны к регистру . Сюда входят все поля, которые используются в качестве ключей на карте, за исключением случаев, когда явно указано, что ключами являются без учета регистра .

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

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

  Чтобы сохранить возможность переключения между форматами YAML и JSON, РЕКОМЕНДУЕТСЯ использовать YAML версии 1.2 вместе с некоторыми дополнительными ограничениями:

  • Теги ДОЛЖНЫ быть ограничены теми, которые разрешены набором правил схемы JSON.
  • Ключи, используемые в картах YAML, ДОЛЖНЫ быть ограничены скалярной строкой, как определено набором правил схемы YAML Failsafe.

  Примечание: Хотя API могут быть определены документами OpenAPI в формате YAML или JSON, тела запроса и ответа API, а также другое содержимое не обязательно должны быть в формате JSON или YAML.

  Структура документа

  Документ OpenAPI МОЖЕТ состоять из одного документа или разделен на несколько связанных частей по усмотрению пользователя. В последнем случае Поля $ref ДОЛЖНЫ использоваться в спецификации для ссылки на эти части, как следует из определений схемы JSON.

  РЕКОМЕНДУЕТСЯ, чтобы корневой документ OpenAPI имел имя: openapi.json или openapi.yaml .

  Типы данных

  Примитивные типы данных в OAS основаны на типах, поддерживаемых спецификацией схемы JSON Wright Draft 00. Обратите внимание, что целое число в качестве типа также поддерживается и определяется как число JSON без дробной или экспоненциальной части. null не поддерживается как тип (см. nullable для альтернативного решения). Модели определяются с помощью объекта схемы, который представляет собой расширенное подмножество спецификации схемы JSON Wright Draft 00.

  Примитивы имеют необязательное свойство модификатора: формат . OAS использует несколько известных форматов для точного определения используемого типа данных. Однако для поддержки потребностей в документации свойство формата является открытой строкой со значением и может иметь любое значение. Такие форматы, как "email" , "uuid" и т. д., МОГУТ использоваться, даже если они не определены этой спецификацией. Типы, которые не сопровождаются свойством формата , соответствуют определению типа в схеме JSON. Инструменты, которые не распознают определенный формат , МОГУТ по умолчанию вернуться к только типу , как если бы формат не был указан.

  OAS определяет следующие форматы:

  тип	9формат 0639	Комментарии
  целое число	int32	32 бита со знаком
  целое число	int64	64 бита со знаком (длинный)
  номер	поплавок
  номер	двойной
  струна
  струна	байт	символов в кодировке base64
  струна	двоичный	любая последовательность октетов
  логическое значение
  струна	Дата	Как определено полная дата — RFC3339
  строка	дата-время	Как определено дата-время — RFC3339
  струна	пароль	Подсказка пользовательскому интерфейсу для скрытия ввода.

  Расширенное форматирование текста

  Во всей спецификации описания полей отмечены как поддерживающие форматирование уценки CommonMark. Там, где инструментарий OpenAPI отображает форматированный текст, он ДОЛЖЕН поддерживать, как минимум, синтаксис уценки, как описано в CommonMark 0.27. Инструментарий МОЖЕТ игнорировать некоторые функции CommonMark для решения проблем безопасности.

  Относительные ссылки в URL-адресах

  Если не указано иное, все свойства, являющиеся URL-адресами, МОГУТ быть относительными ссылками, как определено в RFC3986. Относительные ссылки разрешаются с использованием URL-адресов, определенных в объекте сервера в качестве базового URI.

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

  Схема

  В следующем описании, если поле не указано явно ТРЕБУЕТСЯ или описан как ДОЛЖЕН или СЛЕДУЕТ, его можно считать НЕОБЯЗАТЕЛЬНЫМ.

  Объект OpenAPI

  Это корневой объект документа OpenAPI.

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

  Имя поля	Тип	Описание
  опенапи	струна	ТРЕБУЕТСЯ . Эта строка ДОЛЖНА быть семантическим номером версии спецификации OpenAPI, которую использует документ OpenAPI. 9Поле 0639 openapi СЛЕДУЕТ использовать спецификациям инструментов и клиентам для интерпретации документа OpenAPI. Это , а не , связанный со строкой API info.version .
  информация	Информационный объект	ТРЕБУЕТСЯ . Предоставляет метаданные об API. Метаданные МОГУТ использоваться инструментами по мере необходимости.
  серверы	[Объект сервера]	Массив серверных объектов, которые предоставляют информацию о подключении к целевому серверу. Если Свойство серверов не указано или представляет собой пустой массив, значением по умолчанию будет объект сервера со значением URL-адреса / .
  путей	Пути Объект	ТРЕБУЕТСЯ . Доступные пути и операции для API.
  компоненты	Компоненты Объект	Элемент для хранения различных схем спецификации.
  безопасность	[Объект требования безопасности]	Объявление того, какие механизмы безопасности можно использовать в API. Список значений включает альтернативные объекты требований безопасности, которые можно использовать. Только один из объектов требования безопасности должен быть удовлетворен для авторизации запроса. Отдельные операции могут переопределить это определение. Чтобы сделать безопасность необязательной, в массив можно включить пустое требование безопасности ( {} ).
  теги	[Тег объекта]	Список тегов, используемых спецификацией, с дополнительными метаданными. Порядок тегов можно использовать для отражения их порядка инструментами синтаксического анализа. Не все теги, которые используются объектом операции, должны быть объявлены. Теги, которые не объявлены, МОГУТ быть организованы случайным образом или на основе логики инструментов. Каждое имя тега в списке ДОЛЖНО быть уникальным.
  внешние документы	Объект внешней документации	Дополнительная внешняя документация.

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

  Информационный объект

  Объект предоставляет метаданные об API. Метаданные МОГУТ использоваться клиентами при необходимости и МОГУТ быть представлены в инструментах редактирования или создания документации для удобства.

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

  Имя поля	Тип	Описание
  название	струна	ТРЕБУЕТСЯ . Название API.
  описание	струна	Краткое описание API. Синтаксис CommonMark МОЖЕТ использоваться для форматированного текстового представления.
  условия обслуживания	струна	URL-адрес условий обслуживания для API. ДОЛЖЕН быть в формате URL.
  контакт	Контакт Объект	Контактная информация для открытого API.
  лицензия	Объект лицензии	Информация о лицензии для открытого API.
  версия	струна	ТРЕБУЕТСЯ . Версия документа OpenAPI (отличная от версии спецификации OpenAPI или версии реализации API).

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

  Пример информационного объекта

   {
    "title": "Пример приложения для зоомагазина",
    "description": "Это пример сервера для зоомагазина.",
    "termsOfService": "http://example.com/terms/",
    "контакт": {
      "name": "Поддержка API",
      "url": "http://www. example.com/support",
      "электронная почта": "[email protected]"
    },
    "лицензия": {
      "имя": "Апач 2.0",
      "url": "https://www.apache.org/licenses/LICENSE-2.0.html"
    },
    "версия": "1.0.1"
  }
   

   title: Образец приложения для зоомагазина
  описание: Это пример сервера для зоомагазина.
  Условия обслуживания: http://example.com/terms/
  контакт:
    имя: Поддержка API
    URL-адрес: http://www.example.com/support
    электронная почта: [email protected]
  лицензия:
    имя: Апач 2.0
    URL-адрес: https://www.apache.org/licenses/LICENSE-2.0.html.
  версия: 1.0.1
   

  Контактный объект

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

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

  Имя поля	Тип	Описание
  имя	струна	Идентификационное имя контактного лица/организации.
  адрес	струна	URL-адрес, указывающий на контактную информацию. ДОЛЖЕН быть в формате URL.
  электронная почта	струна	Адрес электронной почты контактного лица/организации. ДОЛЖЕН быть в формате адреса электронной почты.

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

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

   {
    "name": "Поддержка API",
    "url": "http://www.example.com/support",
    "электронная почта": "[email protected]"
  }
   

   имя: Поддержка API
  URL-адрес: http://www.example.com/support
  электронная почта: [email protected]
   

  Объект лицензии

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

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

  Имя поля	Тип	Описание
  имя	струна	ТРЕБУЕТСЯ . Имя лицензии, используемое для API.
  адрес	струна	URL-адрес лицензии, используемой для API. ДОЛЖЕН быть в формате URL.

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

  Пример объекта лицензии

   {
    "имя": "Апач 2.0",
    "url": "https://www.apache.org/licenses/LICENSE-2.0.html"
  }
   

   имя: Apache 2.0
  URL-адрес: https://www.apache.org/licenses/LICENSE-2.0.html.
   

  Объект сервера

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

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

  Имя поля	Тип	Описание
  адрес	струна	ТРЕБУЕТСЯ . URL-адрес целевого хоста. Этот URL-адрес поддерживает серверные переменные и МОЖЕТ быть относительным, чтобы указать, что расположение хоста относится к местоположению, где обслуживается документ OpenAPI. Подстановки переменных будут сделаны, когда переменная названа в { скобки } .
  описание	струна	Необязательная строка, описывающая хост, указанный URL-адресом. Синтаксис CommonMark МОЖЕТ использоваться для форматированного текстового представления.
  переменные	Карта [ строка , объект переменной сервера]	Сопоставление между именем переменной и ее значением. Значение используется для подстановки в шаблоне URL-адреса сервера.

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

  Пример объекта сервера

  Отдельный сервер может быть описан как:

   {
    "url": "https://development.gigantic-server.com/v1",
    "description": "Сервер разработки"
  }
   

   URL-адрес: https://development.gigantic-server.com/v1
  описание: Сервер разработки
   

  Ниже показано, как можно описать несколько серверов, например, серверов объекта OpenAPI :

   {
    "серверы": [
      {
        "url": "https://development.gigantic-server.com/v1",
        "description": "Сервер разработки"
      },
      {
        "url": "https://staging. gigantic-server.com/v1",
        "description": "Промежуточный сервер"
      },
      {
        "url": "https://api.gigantic-server.com/v1",
        "description": "Производственный сервер"
      }
    ]
  }
   

   серверов:
  - URL-адрес: https://development.gigantic-server.com/v1
    описание: Сервер разработки
  - URL-адрес: https://staging.gigantic-server.com/v1
    описание: Промежуточный сервер
  - URL-адрес: https://api.gigantic-server.com/v1
    описание: Рабочий сервер
   

  Ниже показано, как можно использовать переменные для конфигурации сервера:

   {
    "серверы": [
      {
        "url": "https://{имя пользователя}.gigantic-server.com:{порт}/{базовый путь}",
        "description": "Производственный сервер API",
        "переменные": {
          "имя пользователя": {
            "по умолчанию": "демо",
            "description": "это значение назначается поставщиком услуг, в данном примере это `gigantic-server.com`"
          },
          "порт": {
            "перечисление": [
              "8443",
              "443"
            ],
            "по умолчанию": "8443"
          },
          "базовый путь": {
            "по умолчанию": "v2"
          }
        }
      }
    ]
  }
   

   серверов:
  - URL-адрес: https://{имя пользователя}. gigantic-server.com:{порт}/{базовый путь}
    описание: Рабочий сервер API
    переменные:
      имя пользователя:
        # примечание! отсутствие перечисления здесь означает, что это открытое значение
        по умолчанию: демо
        описание: это значение назначается поставщиком услуг, в данном примере это `gigantic-server.com`.
      порт:
        перечисление:
          - '8443'
          - «443»
        по умолчанию: '8443'
      базовый путь:
        # открытый означает, что есть возможность использовать специальные базовые пути, назначенные провайдером, по умолчанию `v2`
        по умолчанию: v2
   

  Объект переменной сервера

  Объект, представляющий переменную сервера для подстановки шаблона URL-адреса сервера.

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

  Имя поля	Тип	Описание
  перечисление	[ строка ]	Перечисление строковых значений, которые следует использовать, если параметры подстановки относятся к ограниченному набору. Массив НЕ ДОЛЖЕН быть пустым.
  по умолчанию	струна	ТРЕБУЕТСЯ . Значение по умолчанию, используемое для замены, которое ДОЛЖНО быть отправлено, если предоставлено альтернативное значение , а не . Обратите внимание, что это поведение отличается от обработки объектов схемы значений по умолчанию, потому что в этих случаях значения параметров являются необязательными. Если определено перечисление , значение ДОЛЖНО существовать в значениях перечисления.
  описание	струна	Необязательное описание серверной переменной. Синтаксис CommonMark МОЖЕТ использоваться для форматированного текстового представления.

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

  Компоненты Объект

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

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

  Имя поля	Тип	Описание
  схемы	Карта[ строка , Объект схемы | Справочный объект]	Объект для хранения многократно используемых объектов схемы.
  ответов	Карта[ строка , Объект ответа | Справочный объект]	Объект для хранения многократно используемых объектов ответа.
  параметры	Карта[ строка , объект параметра | Справочный объект]	Объект для хранения повторно используемых объектов параметров.
  примеры	Карта[ строка , пример объекта | Справочный объект]	Объект для хранения повторно используемых примеров объектов.
  запросТело	Карта[ строка , Объект тела запроса | Справочный объект]	Объект для хранения повторно используемых объектов тела запроса.
  коллекторы	Карта[ строка , Объект заголовка | Справочный объект]	Объект для хранения повторно используемых объектов заголовка.
  Схемы безопасности	Карта[ строка , Объект схемы безопасности | Справочный объект]	Объект для хранения многократно используемых объектов схемы безопасности.
  ссылки	Карта[ строка , Объект ссылки | Справочный объект]	Объект для многократного использования Link Objects.
  обратные вызовы	Карта[ строка , Объект обратного вызова | Справочный объект]	Объект для хранения повторно используемых объектов обратного вызова. 9[a-zA-Z0-9\.\-_]+$ . Примеры имени поля: Пользователь Пользователь_1 Имя пользователя имя пользователя my.org.Пользователь Компоненты Пример объекта "компоненты": { "схемы": { "Общая ошибка": { "тип": "объект", "характеристики": { "код": { "тип": "целое", "формат": "int32" }, "сообщение": { "тип": "строка" } } }, "Категория": { "тип": "объект", "характеристики": { "я бы": { "тип": "целое", "формат": "int64" }, "имя": { "тип": "строка" } } }, "Ярлык": { "тип": "объект", "характеристики": { "я бы": { "тип": "целое", "формат": "int64" }, "имя": { "тип": "строка" } } } }, "параметры": { "скиппарам": { "имя": "пропустить", "в": "запрос", "description": "количество элементов для пропуска", «требуется»: правда, "схема": { "тип": "целое", "формат": "int32" } }, "лимитПарам": { "имя": "лимит", "в": "запрос", "description": "максимальное количество возвращаемых записей", «требуется»: правда, "схема": { "тип": "целое", "формат": "int32" } } }, "ответы": { "Не обнаружена": { "description": "Объект не найден. " }, "Незаконный ввод": { "description": "Недопустимый ввод для операции." }, "Общая ошибка": { "description": "Общая ошибка", "содержание": { "приложение/json": { "схема": { "$ref": "#/компоненты/схемы/Общая ошибка" } } } } }, "Схемы безопасности": { "апи_ключ": { "тип": "апиКей", "имя": "api_key", "в": "заголовок" }, "зоомагазин_auth": { "тип": "oauth3", "течет": { "скрытый": { "authorizationUrl": "http://example.org/api/oauth/dialog", "области": { "write:pets": "изменить питомцев в вашем аккаунте", "read:pets": "читать своих питомцев" } } } } } } компоненты: схемы: Общая ошибка: тип: объект характеристики: код: тип: целое число формат: int32 сообщение: тип: строка Категория: тип: объект характеристики: я бы: тип: целое число формат: int64 имя: тип: строка Ярлык: тип: объект характеристики: я бы: тип: целое число формат: int64 имя: тип: строка параметры: пропуститьПарам: имя: пропустить в: запрос описание: количество элементов, которые нужно пропустить требуется: правда схема: тип: целое число формат: int32 limitПарам: Название: лимит в: запрос описание: максимальное количество возвращаемых записей требуется: правда схема: тип: целое число формат: int32 ответы: Не обнаружена: Описание: Объект не найден. Незаконный ввод: Описание: Недопустимый ввод для операции. Общая ошибка: описание: Общая ошибка содержание: приложение/json: схема: $ref: '#/компоненты/схемы/Общая ошибка' схемы безопасности: ключ_апи: тип: апиКей имя: API_key в: заголовок зоомагазин_auth: тип: oauth3 потоки: скрытый: URL-адрес авторизации: http://example.org/api/oauth/dialog области: write:pets: изменить питомцев в своей учетной записи read:pets: читай своих питомцев Paths Object Содержит относительные пути к отдельным конечным точкам и их операциям. Путь добавляется к URL-адресу из серверного объекта для создания полного URL-адреса. Пути МОГУТ быть пустыми из-за ограничений ACL. Узорчатые поля Узорчатые поля Тип Описание /{путь} Объект элемента пути Относительный путь к отдельной конечной точке. Имя поля ДОЛЖНО начинаться с косой черты ( /). Путь представляет собой , добавленный (без разрешения относительного URL-адреса) к расширенному URL-адресу из поля URL-адреса серверного объекта для создания полного URL-адреса. Шаблоны путей разрешены. При сопоставлении URL-адресов конкретные (не шаблонные) пути будут сопоставляться перед их шаблонными аналогами. Шаблонные пути с одинаковой иерархией, но разными шаблонными именами НЕ ДОЛЖНЫ существовать, поскольку они идентичны. В случае неоднозначного сопоставления инструменты должны решить, какой из них использовать. Этот объект МОЖЕТ быть расширен за счет расширений спецификации. Сопоставление шаблонов путей Предполагая следующие пути, конкретное определение /pets/mine будет сопоставляться первым, если используется: /pets/{petId} /домашние животные/мой Следующие пути считаются идентичными и недействительными: /pets/{petId} /имя питомца} Следующее может привести к неоднозначному разрешению: /{entity}/me /книги/{id} Пример объекта путей { "/домашние питомцы": { "получить": { "description": "Возвращает всех питомцев из системы, к которым у пользователя есть доступ", "ответы": { "200": { "description": "Список питомцев. ", "содержание": { "приложение/json": { "схема": { "тип": "массив", "Предметы": { "$ref": "#/компоненты/схемы/животное" } } } } } } } } } /домашние животные: получить: описание: Возвращает всех питомцев из системы, к которым у пользователя есть доступ ответы: «200»: описание: Список питомцев. содержание: приложение/json: схема: тип: массив Предметы: $ref: '#/компоненты/схемы/домашнее животное' Объект объекта пути Описывает операции, доступные на одном пути. Элемент пути МОЖЕТ быть пустым из-за ограничений ACL. Сам путь по-прежнему открыт для просмотра документации, но они не будут знать, какие операции и параметры доступны. Фиксированные поля Имя поля Тип Описание $ref струна Позволяет внешнее определение этого элемента пути. Структура, на которую делается ссылка, ДОЛЖНА быть в формате объекта элемента пути. В случае, если поле Объект элемента пути появляется как в определенном объекте, так и в объекте, на который указывает ссылка, поведение не определено. резюме струна Необязательная строковая сводка, предназначенная для применения ко всем операциям в этом пути. описание струна Необязательное строковое описание, предназначенное для применения ко всем операциям в этом пути. Синтаксис CommonMark МОЖЕТ использоваться для форматированного текстового представления. получить Операционный Объект Определение операции GET для этого пути. поставить Операционный Объект Определение операции PUT на этом пути. пост Операционный Объект Определение операции POST на этом пути. удалить Операционный Объект Определение операции DELETE на этом пути. опции Операционный Объект Определение операции OPTIONS на этом пути. головка Операционный Объект Определение операции HEAD на этом пути. патч Операционный Объект Определение операции PATCH на этом пути. след Операционный Объект Определение операции TRACE на этом пути. серверы [Объект сервера] Альтернативный массив серверов для обслуживания всех операций по этому пути. параметры [Объект параметра | Справочный объект] Список параметров, применимых ко всем операциям, описанным в этом пути. Эти параметры можно переопределить на уровне операции, но нельзя удалить там. Список НЕ ДОЛЖЕН включать повторяющиеся параметры. Уникальный параметр определяется комбинацией имени и местоположения. Список может использовать ссылочный объект для связи с параметрами, которые определены в компонентах/параметрах объекта OpenAPI. Этот объект МОЖЕТ быть расширен за счет расширений спецификации. Пример объекта элемента пути { "получить": { "description": "Возвращает питомцев по идентификатору", "summary": "Найти питомцев по ID", "operationId": "getPetsById", "ответы": { "200": { "description": "ответ питомца", "содержание": { "*/*": { "схема": { "тип": "массив", "Предметы": { "$ref": "#/компоненты/схемы/домашнее животное" } } } } }, "дефолт": { "description": "полезная нагрузка ошибки", "содержание": { "текст/html": { "схема": { "$ref": "#/компоненты/схемы/ErrorModel" } } } } } }, "параметры": [ { "имя": "идентификатор", "в": "путь", "description": "ID питомца для использования", «требуется»: правда, "схема": { "тип": "массив", "Предметы": { "тип": "строка" } }, "стиль": "простой" } ] } получить: описание: Возвращает питомцев на основе ID резюме: Поиск домашних животных по идентификатору идентификатор операции: getPetsById ответы: «200»: описание: реакция питомца содержание: '*/*' : схема: тип: массив Предметы: $ref: '#/компоненты/схемы/домашнее животное' дефолт: описание: ошибка полезной нагрузки содержание: 'текст/html': схема: $ref: '#/components/schemas/ErrorModel' параметры: - имя: идентификатор в: путь description: ID питомца для использования требуется: правда схема: тип: массив Предметы: тип: строка стиль: простой Operation Object Описывает одну операцию API на пути. Фиксированные поля Имя поля Тип Описание теги [ строка ] Список тегов для управления документацией API. Теги могут использоваться для логической группировки операций по ресурсам или любому другому классификатору. резюме струна Краткое описание того, что делает операция. описание струна Подробное объяснение поведения операции. Синтаксис CommonMark МОЖЕТ использоваться для форматированного текстового представления. внешние документы Объект внешней документации Дополнительная внешняя документация для этой операции. идентификатор операции струна Уникальная строка, используемая для идентификации операции. Идентификатор ДОЛЖЕН быть уникальным среди всех операций, описанных в API. Значение OperationId равно 9.0009 с учетом регистра . Инструменты и библиотеки МОГУТ использовать идентификатор операции для уникальной идентификации операции, поэтому РЕКОМЕНДУЕТСЯ следовать общепринятым соглашениям об именах в программировании. параметры [Объект параметра | Справочный объект] Список параметров, применимых для этой операции. Если параметр уже определен в элементе пути, новое определение переопределит его, но никогда не сможет удалить. Список НЕ ДОЛЖЕН включать повторяющиеся параметры. Уникальный параметр определяется комбинацией имени и местоположения. Список может использовать ссылочный объект для связи с параметрами, которые определены в компонентах/параметрах объекта OpenAPI. запростело Объект тела запроса | Эталонный Объект Тело запроса, применимое к этой операции. requestBody поддерживается только в методах HTTP, где спецификация HTTP 1.1 RFC7231 явно определяет семантику для тела запроса. В других случаях, когда спецификация HTTP расплывчата, requestBody ДОЛЖЕН игнорироваться потребителями. ответов Ответы Объект ТРЕБУЕТСЯ . Список возможных ответов в том виде, в каком они возвращаются при выполнении этой операции. обратные вызовы Карта[ строка , Объект обратного вызова | Справочный объект] Карта возможных внеполосных обратных вызовов, связанных с родительской операцией. Ключ является уникальным идентификатором объекта обратного вызова. Каждое значение на карте — это объект обратного вызова, описывающий запрос, который может быть инициирован поставщиком API, и ожидаемые ответы. устарело логическое значение Объявляет эту операцию устаревшей. Потребители ДОЛЖНЫ воздерживаться от использования объявленной операции. Значение по умолчанию: false . безопасность [Объект требования безопасности] Объявление того, какие механизмы безопасности можно использовать для этой операции. Список значений включает альтернативные объекты требований безопасности, которые можно использовать. Только один из объектов требования безопасности должен быть удовлетворен для авторизации запроса. Чтобы сделать безопасность необязательной, пустое требование безопасности ( {} ) могут быть включены в массив. Это определение переопределяет любой объявленный уровень безопасности верхнего уровня . Чтобы удалить декларацию безопасности верхнего уровня, можно использовать пустой массив. серверы [Объект сервера] Альтернативный серверный массив для обслуживания этой операции. Если альтернативный объект server указан на уровне объекта элемента пути или корневого уровня, он будет переопределен этим значением. Этот объект МОЖЕТ быть расширен за счет расширений спецификации. Пример объекта операции { "метки": [ "домашний питомец" ], "summary": "Обновляет питомца в магазине с данными формы", "operationId": "updatePetWithForm", "параметры": [ { "имя": "идентификатор домашнего животного", "в": "путь", "description": "ID питомца, который необходимо обновить", «требуется»: правда, "схема": { "тип": "строка" } } ], "тело запроса": { "содержание": { "приложение/x-www-форма-urlencoded": { "схема": { "тип": "объект", "характеристики": { "имя": { "description": "Обновлено имя питомца", "тип": "строка" }, "статус": { "description": "Обновлен статус питомца", "тип": "строка" } }, "требуется": ["статус"] } } } }, "ответы": { "200": { "description": "Питомец обновлен. ", "содержание": { "приложение/json": {}, "приложение/xml": {} } }, "405": { "description": "Метод не разрешен", "содержание": { "приложение/json": {}, "приложение/xml": {} } } }, "безопасность": [ { "зоомагазин_аутент": [ "написать: домашние животные", "читать: домашние животные" ] } ] } теги: - домашний питомец резюме: Обновляет питомца в магазине с данными формы идентификатор операции: updatePetWithForm параметры: - имя: petId в: путь description: ID питомца, который нужно обновить требуется: правда схема: тип: строка тело запроса: содержание: 'приложение/x-www-form-urlencoded': схема: характеристики: имя: описание: Обновлено имя питомца тип: строка статус: описание: Обновлен статус питомца тип: строка требуется: - статус ответы: «200»: описание: Питомец обновлен. содержание: 'приложение/json': {} 'приложение/xml': {} «405»: описание: Метод не разрешен содержание: 'приложение/json': {} 'приложение/xml': {} безопасность: - petstore_auth: - напиши: домашние животные - читать: домашние животные Объект внешней документации Позволяет ссылаться на внешний ресурс для получения расширенной документации. Фиксированные поля Имя поля Тип Описание описание струна Краткое описание целевой документации. Синтаксис CommonMark МОЖЕТ использоваться для форматированного текстового представления. адрес строка ТРЕБУЕТСЯ . URL целевой документации. Значение ДОЛЖНО быть в формате URL. Этот объект МОЖЕТ быть расширен за счет расширений спецификации. Пример объекта внешней документации { "description": "Подробнее здесь", "url": "https://example. com" } описание: Подробнее здесь адрес: https://example.com Объект параметра Описывает один рабочий параметр. Уникальный параметр определяется комбинацией имени и местоположения. Расположение параметров Существует четыре возможных расположения параметров, указанных в поле в поле : путь — используется вместе с шаблоном пути, где значение параметра фактически является частью URL-адреса операции. Это не включает хост или базовый путь API. Например, в /items/{itemId} параметр пути равен itemId . Запрос — параметры, которые добавляются к URL-адресу. Например, в /items?id=### , параметр запроса id . Заголовок — настраиваемые заголовки, которые ожидаются как часть запроса. Обратите внимание, что RFC7230 указывает, что имена заголовков нечувствительны к регистру. cookie — используется для передачи определенного значения cookie в API. Фиксированные поля Имя поля Тип Описание имя струна ТРЕБУЕТСЯ . Имя параметра. Имена параметров чувствительны к регистру . Если в является "путь" , поле имени ДОЛЖНО соответствовать выражению шаблона, встречающемуся в поле пути в объекте Paths. Дополнительную информацию см. в разделе Шаблоны путей. Если в — это «заголовок» , а поле имени — это «Принять» , «Content-Type» или «Авторизация» , определение параметра ДОЛЖНО игнорироваться. Во всех остальных случаях имя соответствует имени параметра, используемому свойством в . в струна ТРЕБУЕТСЯ . Расположение параметра. Возможные значения: "запрос" , "заголовок" , "путь" или "cookie" . описание строка Краткое описание параметра. Это может содержать примеры использования. Синтаксис CommonMark МОЖЕТ использоваться для форматированного текстового представления. требуется логическое значение Определяет, является ли этот параметр обязательным. Если расположение параметра "путь" , это свойство REQUIRED и его значение ДОЛЖНО быть true . В противном случае свойство МОЖЕТ быть включено, и его значение по умолчанию равно .ложь . устарело логическое значение Указывает, что параметр устарел и его СЛЕДУЕТ вывести из использования. Значение по умолчанию: false . разрешить пустое значение логическое значение Устанавливает возможность передачи пустых параметров. Это действительно только для параметров запроса и позволяет отправлять параметр с пустым значением. Значение по умолчанию: ложь . Если используется стиль , и если поведение н/д (не может быть сериализовано), значение allowEmptyValue ДОЛЖНО игнорироваться. Использование этого свойства НЕ РЕКОМЕНДУЕТСЯ, так как оно может быть удалено в более поздних версиях. Правила сериализации параметра задаются одним из двух способов. Для более простых сценариев схема и стиль могут описывать структуру и синтаксис параметра. Имя поля Тип Описание стиль струна Описывает, как значение параметра будет сериализовано в зависимости от типа значения параметра. Значения по умолчанию (на основе значения в ): для запроса — форма ; для путь — простой ; для заголовка — простой ; для печенье — форма . взорвать логическое значение Когда это верно, значения параметров типа массива или объекта генерируют отдельные параметры для каждого значения массива или пары ключ-значение карты. Для других типов параметров это свойство не действует. Когда стиль равен форме , значением по умолчанию является true . Для всех остальных стилей значение по умолчанию — false . разрешитьЗарезервировано логическое значение Определяет, СЛЕДУЕТ ли значение параметра разрешать включение зарезервированных символов, как определено в RFC3986 :/?#[]@!$&'()*+,;= , без процентного кодирования. Это свойство применяется только к параметрам со значением в запроса . Значение по умолчанию — false . схема Объект схемы | Эталонный Объект Схема, определяющая тип, используемый для параметра. пример Любой Пример потенциального значения параметра. Пример ДОЛЖЕН соответствовать указанной схеме и свойствам кодирования, если они есть. Поле примера является взаимоисключающим полем примеров . Кроме того, при ссылке на схему , которая содержит пример, значение примера ДОЛЖНО переопределять пример, предоставленный схемой. Чтобы представить примеры типов мультимедиа, которые не могут быть представлены естественным образом в JSON или YAML, строковое значение может содержать пример с экранированием, где это необходимо. примеры Карта[ строка , пример объекта | Справочный объект] Примеры потенциального значения параметра. Каждый пример ДОЛЖЕН содержать значение в правильном формате, указанном в кодировке параметра. Поле примеров является взаимоисключающим полем примеров . Кроме того, при ссылке на схему , которая содержит пример, значение примеров ДОЛЖНО переопределять пример, предоставленный схемой. Для более сложных сценариев свойство content может определять тип носителя и схему параметра. Параметр ДОЛЖЕН содержать либо свойство схемы , либо свойство содержимого , но не то и другое одновременно. Когда пример или примеры предоставляется в сочетании с объектом схемы , пример ДОЛЖЕН следовать предписанной стратегии сериализации для параметра. Имя поля Тип Описание содержание Карта [ строка , объект типа мультимедиа] Карта, содержащая представления параметра. Ключ — это тип носителя, а значение описывает его. Карта ДОЛЖНА содержать только одну запись. Значения стиля Для поддержки распространенных способов сериализации простых параметров определен набор значений стиля . стиль тип в Комментарии матрица примитив , массив , объект путь Параметры стиля пути, определенные RFC6570 этикетка примитив , массив , объект путь Параметры стиля метки, определенные RFC6570 форма примитив , массив , объект запрос , файл cookie Параметры стиля формы, определенные RFC6570. Этот параметр заменяет collectionFormat значением csv (когда explore имеет значение false) или multi (когда explore имеет значение true) из OpenAPI 2.0. простой массив путь , заголовок Параметры простого стиля, определенные RFC6570. Этот параметр заменяет collectionFormat значением csv из OpenAPI 2.0. пробел массив запрос Значения массива, разделенные пробелами. Этот параметр заменяет collectionFormat на ssv из OpenAPI 2.0. труба с разделителями массив запрос Значения массива, разделенные вертикальной чертой. Этот параметр заменяет collectionFormat равным каналам из OpenAPI 2. 0. ГлубинныйОбъект объект запрос Обеспечивает простой способ визуализации вложенных объектов с использованием параметров формы. Примеры исполнения Предположим, что параметр с именем цвет имеет одно из следующих значений: строка -> "синий" массив -> ["синий","черный","коричневый"] объект -> { "R": 100, "G": 200, "B": 150} В следующей таблице показаны примеры различий в отображении для каждого значения. стиль взорвать пустой струна массив объект матрица ложь ;цвет ;цвет=синий ;цвет=синий,черный,коричневый ;цвет=R,100,G,200,B,150 матрица правда ;цвет ;цвет=синий ;цвет=синий;цвет=черный;цвет=коричневый ;R=100;G=200;B=150 этикетка ложь . .синий .синий.черный.коричневый .R.100.G.200.B.150 этикетка правда . .синий .синий.черный.коричневый .R=100.G=200.B=150 форма ложь цвет= цвет=синий цвет=синий,черный,коричневый цвет=R,100,G,200,B,150 форма правда цвет= цвет=синий цвет=синий&цвет=черный&цвет=коричневый R=100&G=200&B=150 простой ложь н/д синий синий, черный, коричневый Р, 100, Г, 200, Б, 150 простой правда н/д синий синий, черный, коричневый R=100,G=200,B=150 пробел ложь н/д н/д синий%20черный%20коричневый Р%20100%20G%20200%20B%20150 труба с разделителями ложь н/д н/д синий|черный|коричневый Р|100|Г|200|В|150 ГлубинныйОбъект правда н/д н/д н/д цвет[R]=100&цвет[G]=200&цвет[B]=150 Этот объект МОЖЕТ быть расширен за счет расширений спецификации. Примеры объектов параметров Параметр заголовка с массивом 64-битных целых чисел: { "имя": "токен", "в": "заголовок", "description": "токен для передачи в качестве заголовка", «требуется»: правда, "схема": { "тип": "массив", "Предметы": { "тип": "целое", "формат": "int64" } }, "стиль": "простой" } имя: токен в: заголовок описание: токен для передачи в качестве заголовка требуется: правда схема: тип: массив Предметы: тип: целое число формат: int64 стиль: простой Параметр пути строкового значения: { "имя": "имя пользователя", "в": "путь", "description": "имя пользователя для извлечения", «требуется»: правда, "схема": { "тип": "строка" } } имя: имя пользователя в: путь описание: имя пользователя для получения требуется: правда схема: тип: строка Необязательный параметр запроса строкового значения, позволяющий использовать несколько значений путем повторения параметра запроса: { "имя": "идентификатор", "в": "запрос", "description": "ID объекта для извлечения", «требуется»: ложь, "схема": { "тип": "массив", "Предметы": { "тип": "строка" } }, "стиль": "форма", "взорваться": правда } имя: идентификатор в: запрос описание: ID объекта для выборки требуется: ложь схема: тип: массив Предметы: тип: строка стиль: форма взорваться: правда Параметр запроса в произвольной форме, допускающий неопределенные параметры определенного типа: { "в": "запрос", "имя": "свободная форма", "схема": { "тип": "объект", "дополнительные свойства": { "тип": "целое число" }, }, "стиль": "форма" } в: запрос Название: FreeForm схема: тип: объект дополнительные свойства: тип: целое число стиль: форма Сложный параметр, использующий содержимое для определения сериализации: { "в": "запрос", "имя": "координаты", "содержание": { "приложение/json": { "схема": { "тип": "объект", "требуется": [ "лат", "длинная" ], "характеристики": { "лат": { "тип": "число" }, "длинная": { "тип": "число" } } } } } } в: запрос имя: координаты содержание: приложение/json: схема: тип: объект требуется: - лат - длинная характеристики: лат: тип: номер длинная: тип: номер Объект тела запроса Описывает одно тело запроса. Фиксированные поля Имя поля Тип Описание описание строка Краткое описание тела запроса. Это может содержать примеры использования. Синтаксис CommonMark МОЖЕТ использоваться для форматированного текстового представления. содержание Карта [ строка , объект типа мультимедиа] ТРЕБУЕТСЯ . Содержимое тела запроса. Ключ представляет собой тип носителя или диапазон типов носителя, а значение описывает его. Для запросов, соответствующих нескольким ключам, применим только самый конкретный ключ. например text/plain перекрывает текст/* требуется логическое значение Определяет, требуется ли тело запроса в запросе. По умолчанию false . Этот объект МОЖЕТ быть расширен за счет расширений спецификации. Примеры тела запроса Тело запроса с определением модели, на которую ссылаются. { "description": "пользователь для добавления в систему", "содержание": { "приложение/json": { "схема": { "$ref": "#/компоненты/схемы/пользователь" }, "Примеры": { "пользователь" : { "summary": "Пример пользователя", "externalValue": "http://foo.bar/examples/user-example.json" } } }, "приложение/xml": { "схема": { "$ref": "#/компоненты/схемы/пользователь" }, "Примеры": { "пользователь" : { "summary": "Пример пользователя в XML", "externalValue": "http://foo.bar/examples/user-example.xml" } } }, "текст/обычный": { "Примеры": { "пользователь" : { "summary": "Пример пользователя в текстовом формате", "externalValue": "http://foo.bar/examples/user-example.txt" } } }, "*/*": { "Примеры": { "пользователь" : { "summary": "Пример пользователя в другом формате", "externalValue": "http://foo. bar/examples/user-example.whatever" } } } } } описание: пользователь для добавления в систему содержание: 'приложение/json': схема: $ref: '#/компоненты/схемы/пользователь' Примеры: пользователь: резюме: пример пользователя externalValue: 'http://foo.bar/examples/user-example.json' 'приложение/xml': схема: $ref: '#/компоненты/схемы/пользователь' Примеры: пользователь: резюме: Пример пользователя в XML externalValue: 'http://foo.bar/examples/user-example.xml' 'текст/обычный': Примеры: пользователь: резюме: пример пользователя в текстовом формате externalValue: 'http://foo.bar/examples/user-example.txt' '*/*': Примеры: пользователь: резюме: пример пользователя в другом формате externalValue: 'http://foo.bar/examples/user-example.whatever' Основной параметр, представляющий собой массив строковых значений: { "description": "пользователь для добавления в систему", "содержание": { "текст/обычный": { "схема": { "тип": "массив", "Предметы": { "тип": "строка" } } } } } описание: пользователь для добавления в систему требуется: правда содержание: текст/обычный: схема: тип: массив Предметы: тип: строка Объект типа носителя Каждый объект типа носителя предоставляет схему и примеры для типа носителя, определяемого его ключом. Фиксированные поля Имя поля Тип Описание схема Объект схемы | Эталонный Объект Схема, определяющая содержимое запроса, ответа или параметра. пример Любой Пример типа носителя. Образец объекта ДОЛЖЕН быть в правильном формате, указанном типом носителя. Поле примера является взаимоисключающим полем 9.0639 примеров полей. Кроме того, при ссылке на схему , содержащую пример, значение примера ДОЛЖНО переопределять пример , предоставленный схемой. примеры Карта[ строка , пример объекта | Справочный объект] Примеры типа носителя. Каждый пример объекта ДОЛЖЕН соответствовать типу носителя и указанной схеме, если она присутствует. Поле примеров является взаимоисключающим полем пример поле. Кроме того, при ссылке на схему , которая содержит пример, значение примеров ДОЛЖНО переопределять пример, предоставленный схемой. кодировка Карта [ строка , объект кодирования] Сопоставление между именем свойства и информацией о его кодировке. Ключ, являющийся именем свойства, ДОЛЖЕН существовать в схеме как свойство. Объект кодирования ДОЛЖЕН применяться только к requestBody , когда тип мультимедиа multipart или application/x-www-form-urlencoded . Этот объект МОЖЕТ быть расширен за счет расширений спецификации. Примеры типов носителей { "приложение/json": { "схема": { "$ref": "#/компоненты/схемы/домашнее животное" }, "Примеры": { "кошка" : { "summary": "Пример кота", "ценность": { "имя": "Пушистый", "petType": "Кошка", "белый цвет", "мужской пол", "порода": "персидская" } }, "собака": { "summary": "Пример собаки с кошачьим именем", "ценность" : { "имя": "Пума", "petType": "Собака", "черный цвет", "женский пол", "порода": "Смешанная" }, "лягушка": { "$ref": "#/компоненты/примеры/пример-лягушки" } } } } } приложение/json: схема: $ref: "#/компоненты/схемы/домашнее животное" Примеры: кошка: Резюме: Пример кота ценность: имя: Пушистый petType: Кошка белый цвет мужской пол порода: персидская собака: резюме: Пример собаки с кошачьим именем ценность: имя: Пума petType: Собака черный цвет женский пол порода: смешанная лягушка: $ref: "#/компоненты/примеры/пример-лягушки" Рекомендации по загрузке файлов В отличие от спецификации 2. 0, содержимое ввода/вывода файла в OpenAPI описывается той же семантикой, что и любой другой тип схемы. В частности: # контент, переданный с кодировкой base64 схема: тип: строка формат: base64 # контент передается в двоичном виде (октетный поток): схема: тип: строка формат: бинарный Эти примеры относятся либо к входным полезным нагрузкам загрузки файлов, либо к полезным нагрузкам ответа. requestBody для отправки файла в операции POST может выглядеть следующим образом: requestBody: содержание: приложение/октетный поток: схема: # бинарный файл любого типа тип: строка формат: бинарный Кроме того, МОГУТ быть указаны определенные типы носителей: # могут быть указаны несколько конкретных типов носителей: тело запроса: содержание: # бинарный файл типа png или jpeg 'изображение/jpeg': схема: тип: строка формат: бинарный 'изображение/png': схема: тип: строка формат: бинарный Для загрузки нескольких файлов ДОЛЖЕН использоваться тип мультимедиа multipart : requestBody: содержание: составные/данные формы: схема: характеристики: # Имя свойства 'file' будет использоваться для всех файлов. файл: тип: массив Предметы: тип: строка формат: бинарный Поддержка тела запроса x-www-form-urlencoded можно использовать определение: тело запроса: содержание: приложение/x-www-форма-urlencoded: схема: тип: объект характеристики: я бы: тип: строка формат: UUID адрес: # сложные типы преобразуются в строки для поддержки RFC 1866 тип: объект характеристики: {} В этом примере содержимое requestBody ДОЛЖНО быть преобразовано в строку в соответствии с RFC1866 при передаче на сервер. Кроме того, комплексный объект поля адреса будет преобразован в строку. При передаче сложных объектов в типе контента application/x-www-form-urlencoded стратегия сериализации таких свойств по умолчанию описана в свойстве Encoding Object ‘s style как form . Особые замечания для multipart Content Обычно используется multipart/form-data как Content-Type при передаче тела запроса в операции. В отличие от 2.0, 9Схема 0639 ТРЕБУЕТСЯ для определения входных параметров операции при использовании многокомпонентного контента . Это поддерживает сложные структуры, а также поддерживает механизмы для загрузки нескольких файлов. При передаче типов multipart границы МОГУТ использоваться для разделения разделов передаваемого контента — таким образом, для multipart определены следующие значения по умолчанию Content-Type : Если свойство является примитивным , или массив примитивных значений, Content-Type по умолчанию равен текстовый/обычный Если свойство является сложным или представляет собой массив сложных значений, Content-Type по умолчанию — application/json Если свойство имеет тип : строка с форматом : двоичный формат или формат : base64 (также известный как файловый объект), Content-Type по умолчанию — application/octet-stream Примеры: requestBody: содержание: составные/данные формы: схема: тип: объект характеристики: я бы: тип: строка формат: UUID адрес: # Content-Type по умолчанию для объектов - `application/json` тип: объект характеристики: {} изображение профиля: # Content-Type по умолчанию для строки/двоичного файла: `application/octet-stream` тип: строка формат: бинарный дети: # Content-Type по умолчанию для массивов основан на `внутреннем` типе (здесь text/plain) тип: массив Предметы: тип: строка адреса: # Content-Type по умолчанию для массивов основан на `внутреннем` типе (показан объект, поэтому в этом примере `application/json`) тип: массив Предметы: тип: '#/компоненты/схемы/адрес' Атрибут кодирования введен для предоставления вам контроля над сериализацией частей составных тел запросов . Этот атрибут только применим к составным телам запросов и application/x-www-form-urlencoded . Объект кодирования Одно определение кодирования, примененное к одному свойству схемы. Фиксированные поля Имя поля Тип Описание тип контента струна Content-Type для кодирования определенного свойства. Значение по умолчанию зависит от типа свойства: для строка с форматом является бинарным – приложение/октет-поток ; для остальных типов примитивов — text/plain ; для объекта - application/json ; для массива – значение по умолчанию определяется на основе внутреннего типа. Значение может быть конкретным типом носителя (например, application/json ), тип мультимедиа с подстановочными знаками (например, image/* ) или список двух типов, разделенных запятыми. коллекторы Карта[ строка , Объект заголовка | Справочный объект] Карта, позволяющая предоставлять дополнительную информацию в виде заголовков, например Content-Disposition . Content-Type описывается отдельно и ДОЛЖЕН быть проигнорирован в этом разделе. Это свойство ДОЛЖНО игнорироваться, если тип носителя тела запроса не является составной . стиль струна Описывает, как будет сериализовано конкретное значение свойства в зависимости от его типа. Подробные сведения о свойстве стиля см. в разделе Объект параметра. Поведение соответствует тем же значениям, что и параметры запроса , включая значения по умолчанию. Это свойство ДОЛЖНО игнорироваться, если тип носителя тела запроса не application/x-www-form-urlencoded . взорвать логическое значение Когда это верно, значения свойства типа массива или объекта генерируют отдельные параметры для каждого значения массива или пары ключ-значение карты. Для других типов свойств это свойство не действует. Когда стиль равен форме , значением по умолчанию является true . Для всех остальных стилей значение по умолчанию — false . Это свойство ДОЛЖНО игнорироваться, если тип носителя тела запроса не равен 9.0639 приложение/x-www-form-urlencoded . разрешитьЗарезервировано логическое значение Определяет, СЛЕДУЕТ ли значение параметра разрешать включение зарезервированных символов, как определено в RFC3986 :/?#[]@!$&'()*+,;= , без процентного кодирования. Значение по умолчанию — false . Это свойство ДОЛЖНО игнорироваться, если тип носителя тела запроса не application/x-www-form-urlencoded . Этот объект МОЖЕТ быть расширен за счет расширений спецификации. Пример объекта кодирования requestBody: содержание: составной/смешанный: схема: тип: объект характеристики: я бы: # по умолчанию текстовый/обычный тип: строка формат: UUID адрес: # по умолчанию это приложение/json тип: объект характеристики: {} историяМетаданные: # нужно объявить формат XML! описание: метаданные в формате XML тип: объект характеристики: {} изображение профиля: # по умолчанию используется application/octet-stream, необходимо объявить только тип изображения! тип: строка формат: бинарный кодировка: историяМетаданные: # требуется XML Content-Type в кодировке utf-8 ContentType: приложение/xml; кодировка = utf-8 изображение профиля: # принимаем только png/jpeg contentType: изображение/png, изображение/jpeg заголовки: X-Rate-Limit-Limit: описание: Количество разрешенных запросов в текущем периоде схема: тип: целое число Responses Object Контейнер для ожидаемых ответов операции. Контейнер сопоставляет код ответа HTTP с ожидаемым ответом. Документация не обязательно должна охватывать все возможные коды ответов HTTP, поскольку они могут быть неизвестны заранее. Однако ожидается, что документация будет охватывать успешный ответ операции и любые известные ошибки. по умолчанию МОЖЕТ использоваться в качестве объекта ответа по умолчанию для всех кодов HTTP которые не рассматриваются отдельно в спецификации. Объект ответов ДОЛЖЕН содержать по крайней мере один код ответа, и он ДОЛЖЕН быть ответом на успешный вызов операции. Фиксированные поля Имя поля Тип Описание по умолчанию Объект ответа | Эталонный Объект Документация ответов, отличных от заявленных для конкретных кодов ответов HTTP. Используйте это поле для покрытия необъявленных ответов. Справочный объект может ссылаться на ответ, который определяется в разделе компонентов/ответов объекта OpenAPI. Узорчатые поля Узорчатые поля Тип Описание Код состояния HTTP Объект ответа | Эталонный Объект В качестве имени свойства можно использовать любой код состояния HTTP, но только одно свойство на код, чтобы описать ожидаемый ответ для этого кода состояния HTTP. Справочный объект может ссылаться на ответ, определенный в разделе компонентов/ответов объекта OpenAPI. Это поле ДОЛЖНО быть заключено в кавычки (например, «200») для совместимости между JSON и YAML. Чтобы определить диапазон кодов ответа, это поле МОЖЕТ содержать подстановочный знак 9 в верхнем регистре.0639 х . Например, 2XX представляет все коды ответа между [200-299] . Допускаются только следующие определения диапазона: 1XX , 2XX , 3XX , 4XX и 5XX . Если ответ определен с использованием явного кода, явное определение кода имеет приоритет над определением диапазона для этого кода. Этот объект МОЖЕТ быть расширен за счет расширений спецификации. Ответы Пример объекта Ответ 200 для успешной операции и ответ по умолчанию для других (подразумевающий ошибку): { "200": { "description": "животное, которое нужно вернуть", "содержание": { "приложение/json": { "схема": { "$ref": "#/компоненты/схемы/домашнее животное" } } } }, "дефолт": { "description": "Непредвиденная ошибка", "содержание": { "приложение/json": { "схема": { "$ref": "#/компоненты/схемы/ErrorModel" } } } } } '200': описание: домашнее животное, которое нужно вернуть содержание: приложение/json: схема: $ref: '#/компоненты/схемы/домашнее животное' дефолт: описание: Непредвиденная ошибка содержание: приложение/json: схема: $ref: '#/components/schemas/ErrorModel' Response Object Описывает один ответ от операции API, включая время разработки, статический связывает с операциями на основе ответа. Фиксированные поля Имя поля Тип Описание описание струна ТРЕБУЕТСЯ . Краткое описание ответа. Синтаксис CommonMark МОЖЕТ использоваться для форматированного текстового представления. коллекторы Карта[ строка , Объект заголовка | Справочный объект] Сопоставляет имя заголовка с его определением. RFC7230 указывает, что имена заголовков нечувствительны к регистру. Если заголовок ответа определен с именем "Content-Type" , его ДОЛЖНО игнорировать. содержание Карта [ строка , объект типа мультимедиа] Карта, содержащая описания потенциальных полезных данных ответа. Ключ представляет собой тип носителя или диапазон типов носителя, а значение описывает его. Для ответов, соответствующих нескольким ключам, применим только самый конкретный ключ. например text/plain переопределяет text/* ссылки Карта[ строка , Объект ссылки | Справочный объект] Карта ссылок операций, по которым можно перейти из ответа. Ключ карты — это короткое имя для ссылки, соответствующее ограничениям именования имен для объектов-компонентов. Этот объект МОЖЕТ быть расширен за счет расширений спецификации. Примеры объектов ответа Ответ массива сложного типа: { "description": "Ответ сложного массива объектов", "содержание": { "приложение/json": { "схема": { "тип": "массив", "Предметы": { "$ref": "#/компоненты/схемы/VeryComplexType" } } } } } описание: Ответ массива сложных объектов содержание: приложение/json: схема: тип: массив Предметы: $ref: '#/компоненты/схемы/VeryComplexType' Ответ строкового типа: { "description": "Простой строковый ответ", "содержание": { "текст/обычный": { "схема": { "тип": "строка" } } } } описание: простой строковый ответ содержание: текст/обычный: схема: тип: строка Простой текстовый ответ с заголовками: { "description": "Простой строковый ответ", "содержание": { "текст/обычный": { "схема": { "тип": "строка", "пример": "вау!" } } }, "заголовки": { "Ограничение скорости X-предела": { "description": "Количество разрешенных запросов в текущем периоде", "схема": { "тип": "целое число" } }, "X-Rate-Limit-Remaining": { "description": "Количество оставшихся запросов в текущем периоде", "схема": { "тип": "целое число" } }, "X-Rate-Limit-Reset": { "description": "Количество секунд, оставшихся до конца текущего периода", "схема": { "тип": "целое число" } } } } описание: Простой строковый ответ содержание: текст/обычный: схема: тип: строка пример: "уоу!" заголовки: X-Rate-Limit-Limit: описание: Количество разрешенных запросов в текущем периоде схема: тип: целое число X-Rate-Limit-Remaining: описание: количество оставшихся запросов в текущем периоде схема: тип: целое число X-Rate-Limit-Reset: описание: Количество секунд, оставшихся в текущем периоде схема: тип: целое число Ответ без возвращаемого значения: { "description": "объект создан" } описание: объект создан Объект обратного вызова Карта возможных внеполосных обратных вызовов, связанных с родительской операцией. Каждое значение на карте представляет собой объект элемента пути, описывающий набор запросов, которые могут быть инициированы поставщиком API, и ожидаемые ответы. Ключевое значение, используемое для идентификации объекта элемента пути, представляет собой выражение, оцениваемое во время выполнения и идентифицирующее URL-адрес, используемый для операции обратного вызова. Узорчатые поля Узорчатые поля Тип Описание {выражение} Объект элемента пути Объект элемента пути, используемый для определения запроса обратного вызова и ожидаемых ответов. Полный пример доступен. Этот объект МОЖЕТ быть расширен за счет расширений спецификации. Выражение ключа Ключ, идентифицирующий объект элемента пути, представляет собой выражение времени выполнения, которое можно оценить в контексте HTTP-запроса/ответа времени выполнения для определения URL-адреса, который будет использоваться для запроса обратного вызова. Простым примером может быть $request.body#/url . Однако с помощью выражения времени выполнения можно получить доступ к полному сообщению HTTP. Это включает в себя доступ к любой части тела, на которую может ссылаться указатель JSON RFC6901. Например, для следующего HTTP-запроса: POST /subscribe/myevent?queryUrl=http://clientdomain.com/stillrunning HTTP/1.1 Хост: example.org Тип содержимого: приложение/json Длина контента: 187 { "failedUrl": "http://clientdomain.com/failed", "URL-адреса успеха": [ "http://clientdomain.com/fast", "http://clientdomain.com/medium", "http://clientdomain.com/slow" ] } 201 Создано Расположение: http://example.org/subscription/1. В следующих примерах показано, как оцениваются различные выражения, при условии, что операция обратного вызова имеет параметр пути с именем eventType и параметр запроса с именем queryUrl . Выражение Значение URL-адрес $ http://example. org/subscribe/myevent?queryUrl=http://clientdomain.com/stillrunning $метод ПОЧТ $request.path.eventType мое событие $request.query.queryUrl http://clientdomain.com/stillrunning $request.header.content-Type приложение/json $request.body#/failedUrl http://clientdomain.com/failed $request.body#/successUrls/2 http://clientdomain.com/medium $response.header.Расположение http://example.org/subscription/1 Примеры объектов обратного вызова В следующем примере используется предоставленный пользователем параметр строки запроса queryUrl для определения URL-адреса обратного вызова. Это пример того, как использовать объект обратного вызова для описания обратного вызова WebHook, который идет с операцией подписки, чтобы включить регистрацию для WebHook. мойОбратный звонок: '{$request.query.queryUrl}': почта: тело запроса: описание: Полезная нагрузка обратного вызова содержание: 'приложение/json': схема: $ref: '#/компоненты/схемы/SomePayload' ответы: «200»: описание: обратный вызов успешно обработан В следующем примере показан обратный вызов, в котором сервер жестко закодирован, но параметры строки запроса заполняются из свойств id и email в тексте запроса. транзакцияОбратный вызов: 'http://notificationServer.com?transactionId={$request.body#/id}&email={$request.body#/email}': почта: тело запроса: описание: Полезная нагрузка обратного вызова содержание: 'приложение/json': схема: $ref: '#/компоненты/схемы/SomePayload' ответы: «200»: описание: обратный вызов успешно обработан Пример объекта Фиксированные поля Имя поля Тип Описание резюме струна Краткое описание примера. описание струна Подробное описание примера. Синтаксис CommonMark МОЖЕТ использоваться для форматированного текстового представления. значение Любой Пример встроенного литерала. Поле значения и поле externalValue являются взаимоисключающими. Чтобы представить примеры типов мультимедиа, которые не могут быть представлены естественным образом в JSON или YAML, используйте строковое значение, содержащее пример, с экранированием, где это необходимо. внешнее значение струна URL-адрес, указывающий на буквальный пример. Это дает возможность ссылаться на примеры, которые нелегко включить в документы JSON или YAML. 9Поле значения 0639 и поле externalValue являются взаимоисключающими. Этот объект МОЖЕТ быть расширен за счет расширений спецификации. Во всех случаях ожидается, что значение примера будет совместимо со схемой типа связанной с ним стоимости. Инструментальные реализации МОГУТ выбрать автоматически проверять совместимость и отклонять примеры значений, если они несовместимы. Пример Примеры объектов В теле запроса: запростело: содержание: 'приложение/json': схема: $ref: '#/компоненты/схемы/адрес' Примеры: фу: резюме: пример foo значение: {"foo": "бар"} бар: резюме: пример бара значение: {"бар": "баз"} 'приложение/xml': Примеры: xmlПример: резюме: это пример в XML externalValue: 'http://example.org/examples/address-example.xml' 'текст/обычный': Примеры: текстПример: резюме: Это текстовый пример externalValue: 'http://foo.bar/examples/address-example.txt' В параметре: параметры: - имя: 'zipCode' в: 'запрос' схема: тип: 'строка' формат: 'почтовый индекс' Примеры: zip-пример: $ref: '#/компоненты/примеры/zip-пример' В ответ: ответов: «200»: описание: ваша автомобильная встреча была забронирована содержание: приложение/json: схема: $ref: '#/компоненты/схемы/SuccessResponse' Примеры: подтверждение-успех: $ref: '#/компоненты/примеры/подтверждение успеха' Link Object Объект Link представляет собой возможную ссылку времени разработки для ответа. Наличие ссылки не гарантирует, что вызывающая сторона сможет успешно вызвать ее, а скорее обеспечивает известную взаимосвязь и механизм обхода между ответами и другими операциями. В отличие от динамических ссылок (т. е. ссылок, предоставленных в полезной нагрузке ответа), механизм связывания OAS не требует информации о ссылке в ответе среды выполнения. Для вычисления ссылок и предоставления инструкций по их выполнению выражение времени выполнения используется для доступа к значениям в операции и использования их в качестве параметров при вызове связанной операции. Фиксированные поля Имя поля Тип Описание рабочийRef струна Относительная или абсолютная ссылка URI на операцию OAS. Это поле является взаимоисключающим из operationId и ДОЛЖЕН указывать на объект операции. Относительные значения operationRef МОГУТ использоваться для обнаружения существующего объекта операции в определении OpenAPI. идентификатор операции струна Имя существующей разрешимой операции OAS, определенной с помощью уникального идентификатора операции . Это поле является взаимоисключающим по отношению к полю operationRef . параметры Карта[ строка , Любая | {выражение}] Карта, представляющая параметры для передачи в операцию, указанную с помощью operationId или идентифицированную с помощью operationRef . Ключ — это имя используемого параметра, тогда как значение может быть константой или выражением, которое нужно вычислить и передать в связанную операцию. Имя параметра можно уточнить, используя расположение параметра [{in}.]{name} для операций, использующих одно и то же имя параметра в разных местах (например, path.id). запростело Любой | {выражение} Буквенное значение или {выражение} для использования в качестве тела запроса при вызове целевой операции. описание струна Описание ссылки. Синтаксис CommonMark МОЖЕТ использоваться для форматированного текстового представления. сервер Объект сервера Объект сервера, который будет использоваться целевой операцией. Этот объект МОЖЕТ быть расширен за счет расширений спецификации. Связанная операция ДОЛЖНА быть идентифицирована с помощью operationRef или operationId . В случае operationId он ДОЛЖЕН быть уникальным и разрешаться в рамках документа OAS. Из-за возможного конфликта имен предпочтительным является синтаксис operationRef . для спецификаций с внешними ссылками. Примеры Вычисление ссылки из операции запроса, где $request.path.id используется для передачи параметра запроса связанной операции. путей: /пользователи/{идентификатор}: параметры: - имя: идентификатор в: путь требуется: правда описание: идентификатор пользователя, как userId схема: тип: строка получить: ответы: «200»: описание: возвращаемый пользователь содержание: приложение/json: схема: тип: объект характеристики: uuid: # уникальный идентификатор пользователя тип: строка формат: UUID ссылки: адрес: # идентификатор операции целевой ссылки идентификатор операции: getUserAddress параметры: # получить поле `id` из параметра пути запроса с именем `id` идентификатор пользователя: $ request. path.id # элемент пути связанной операции /users/{идентификатор пользователя}/адрес: параметры: - имя: идентификатор пользователя в: путь требуется: правда описание: идентификатор пользователя, как userId схема: тип: строка # связанная операция получить: идентификатор операции: getUserAddress ответы: «200»: описание: адрес пользователя Если выражение среды выполнения не может быть оценено, в целевую операцию не передается значение параметра. Значения из тела ответа можно использовать для управления связанной операцией. ссылки: адрес: идентификатор операции: getUserAddressByUUID параметры: # получить поле `uuid` из поля `uuid` в теле ответа userUuid: $response.body#/uuid Клиенты переходят по всем ссылкам на свое усмотрение. Ни разрешения, ни возможность сделать успешный вызов по этой ссылке не гарантируются. исключительно наличием отношений. OperationRef Примеры Поскольку ссылки на operationId МОГУТ быть НЕвозможными ( operationId является необязательным поле в объекте операции), ссылки МОГУТ также быть сделаны через относительные ссылки operationRef : : Пользовательские репозитории: # возвращает массив '#/components/schemas/repository' OperationRef: '#/paths/~12. 0~1repositories~1{username}/get' параметры: имя пользователя: $response.body#/имя пользователя или абсолютная OperationRef : ссылки: Пользовательские репозитории: # возвращает массив '#/components/schemas/repository' OperationRef: 'https://na2.gigantic-server.com/#/paths/~12.0~1repositories~1{username}/get' параметры: имя пользователя: $response.body#/имя пользователя Обратите внимание, что при использовании operationRef экранированная косая черта необходима, когда используя ссылки JSON. Выражения среды выполнения Выражения среды выполнения позволяют определять значения на основе информации, которая будет доступна только в HTTP-сообщении при фактическом вызове API. Этот механизм используется объектами Link и Callback Objects. Выражение среды выполнения определяется следующим синтаксисом ABNF: выражение = ("$url" / "$method" / "$statusCode" / "$request. " / "_" / "`" / "|" / "~" / ЦИФРА / АЛЬФА Здесь json-pointer взят из RFC 6901, char из RFC 7159 и токен из RFC 7230. В таблице ниже приведены примеры выражений времени выполнения и примеры их использования в значении: Примеры Местоположение источника пример выражения отмечает Метод HTTP $метод Допустимые значения для метода $method будут такими же, как и для операции HTTP. Запрошенный тип носителя $request.header.accept Параметр запроса $request.path.id Параметры запроса ДОЛЖНЫ быть объявлены в разделе параметров родительской операции, иначе они не могут быть оценены. Сюда входят заголовки запросов. Свойство тела запроса $request. body#/пользователь/uuid В операциях, которые принимают полезные нагрузки, могут быть сделаны ссылки на части requestBody или все тело. URL запроса $ URL Значение ответа $response.body#/статус В операциях, которые возвращают полезные данные, могут быть сделаны ссылки на части тела ответа или на все тело. Заголовок ответа $response.header.Сервер Доступны только отдельные значения заголовка Выражения времени выполнения сохраняют тип значения, на которое указывает ссылка. Выражения можно встраивать в строковые значения, окружая выражение фигурными скобками {} . Объект заголовка повторяет структуру объекта параметров со следующими изменениями: название НЕ ДОЛЖНО указываться, оно указывается в соответствующем заголовки карта. в НЕ ДОЛЖНО быть указано, это неявно в заголовке . Все черты, на которые влияет местоположение, ДОЛЖНЫ быть применимы к местоположению заголовка (например, стиль ). Простой заголовок типа целое число : { "description": "Количество разрешенных запросов в текущем периоде", "схема": { "тип": "целое число" } } описание: Количество разрешенных запросов в текущем периоде схема: тип: целое число Объект тега Добавляет метаданные к одному тегу, используемому объектом операции. Не обязательно иметь объект тега для каждого тега, определенного в экземплярах объекта операции. Фиксированные поля Имя поля Тип Описание имя струна ТРЕБУЕТСЯ . Имя тега. описание струна Краткое описание тега. Синтаксис CommonMark МОЖЕТ использоваться для форматированного текстового представления. внешние документы Объект внешней документации Дополнительная внешняя документация для этого тега. Этот объект МОЖЕТ быть расширен за счет расширений спецификации. Пример объекта тега { "имя": "домашнее животное", "description": "Операции с домашними животными" } имя: домашнее животное описание: Операции с домашними животными Объект ссылки Простой объект, позволяющий ссылаться на другие компоненты в спецификации, как внутри, так и снаружи. Объект ссылки определяется ссылкой JSON и следует той же структуре, поведению и правилам. Для этой спецификации разрешение ссылки выполняется в соответствии со спецификацией JSON Reference, а не спецификацией JSON Schema. Фиксированные поля Имя поля Тип Описание $ref струна ТРЕБУЕТСЯ . Ссылочная строка. Этот объект не может быть дополнен дополнительными свойствами, и любые добавленные свойства ДОЛЖНЫ игнорироваться. Пример ссылочного объекта { "$ref": "#/компоненты/схемы/домашнее животное" } $ref: '#/components/schemas/Pet' Пример документа относительной схемы { "$ref": "Pet.json" } $ref: Pet.yaml Родственные документы со встроенной схемой Пример { "$ref": "definitions.json#/домашнее животное" } $ref: определения.yaml#/домашнее животное Объект схемы Объект схемы позволяет определять типы входных и выходных данных. Эти типы могут быть объектами, а также примитивами и массивами. Этот объект является расширенным подмножеством спецификации схемы JSON Wright Draft 00. Дополнительные сведения о свойствах см. в разделе Ядро схемы JSON и Проверка схемы JSON. Если не указано иное, определения свойств следуют схеме JSON. Свойства Следующие свойства взяты непосредственно из определения схемы JSON и соответствуют тем же спецификациям: title кратно максимум эксклюзивМаксимум минимум эксклюзивМинимум максимальная длина минДлина Шаблон (Эта строка ДОЛЖНА быть допустимым регулярным выражением в соответствии с диалектом регулярных выражений Ecma-262 Edition 5.1) Максимальное количество предметов минЭлементы уникальных предметов МаксСвойства минСвойства требуется перечисление Следующие свойства взяты из определения схемы JSON, но их определения были скорректированы в соответствии со спецификацией OpenAPI. тип — значение ДОЛЖНО быть строкой. Несколько типов через массив не поддерживаются. allOf — встроенная или ссылочная схема ДОЛЖНА быть объектом схемы, а не стандартной схемой JSON. oneOf — встроенная или ссылочная схема ДОЛЖНА быть объектом схемы, а не стандартной схемой JSON. anyOf — встроенная или ссылочная схема ДОЛЖНА быть объектом схемы, а не стандартной схемой JSON. нет — встроенная или ссылочная схема ДОЛЖНА быть объектом схемы, а не стандартной схемой JSON. элементов — значение ДОЛЖНО быть объектом, а не массивом. Встроенная или ссылочная схема ДОЛЖНА быть объектом схемы, а не стандартной схемой JSON. элементов ДОЛЖЕН присутствовать, если тип — это массив . Свойства . Определения свойств ДОЛЖНЫ быть объектом схемы, а не стандартной схемой JSON (встроенной или указанной). AdditionalProperties — значение может быть логическим или объектным. Встроенная или ссылочная схема ДОЛЖНА быть объектом схемы, а не стандартной схемой JSON. В соответствии со схемой JSON, AdditionalProperties по умолчанию имеет значение true . Описание — синтаксис CommonMark МОЖЕТ использоваться для форматированного текстового представления. Формат — дополнительные сведения см. в разделе «Форматы типов данных». Опираясь на определенные форматы схемы JSON, OAS предлагает несколько дополнительных предопределенных форматов. по умолчанию — значение по умолчанию представляет собой то, что потребитель входных данных принял бы за значение схемы, если оно не указано. В отличие от схемы JSON, значение ДОЛЖНО соответствовать определенному типу для объекта схемы, определенного на том же уровне. Например, если типа является строкой , то по умолчанию может быть "foo" , но не может быть 1 . В качестве альтернативы, в любое время, когда можно использовать объект схемы, вместо него можно использовать ссылочный объект. Это позволяет ссылаться на определения вместо их встроенного определения. Дополнительные свойства, определенные спецификацией схемы JSON и не упомянутые здесь, строго не поддерживаются. Помимо полей подмножества схемы JSON, следующие поля МОГУТ использоваться для дальнейшей документации схемы: Фиксированные поля Имя поля Тип Описание Обнуляемый логическое значение Значение true добавляет "null" к разрешенному типу, заданному ключевым словом type , только если тип явно определен в том же объекте схемы. Другие ограничения объекта схемы сохраняют свое определенное поведение и, следовательно, могут запрещать использование null в качестве значения. Значение false оставляет указанный тип или тип по умолчанию без изменений. Значение по умолчанию — false . дискриминатор Дискриминатор Объект Добавляет поддержку полиморфизма. Дискриминатор — это имя объекта, которое используется для различения других схем, которые могут удовлетворять описанию полезной нагрузки. Дополнительные сведения см. в разделе Композиция и наследование. Только для чтения логическое значение Относится только к определениям схемы «свойства» . Объявляет свойство как «только для чтения». Это означает, что он МОЖЕТ быть отправлен как часть ответа, но НЕ ДОЛЖЕН быть отправлен как часть запроса. Если свойство помечено как readOnly , являющееся true и находится в списке required , required повлияет только на ответ. Свойство НЕ ДОЛЖНО быть помечено как только для чтения и writeOnly является истинным . Значение по умолчанию: false . только запись логическое значение Относится только к определениям схемы «свойства» . Объявляет свойство как «только для записи». Следовательно, он МОЖЕТ быть отправлен как часть запроса, но НЕ ДОЛЖЕН быть отправлен как часть ответа. Если свойство помечено как writeOnly , являющееся true и находится в списке обязательных , требуемый вступит в силу только по запросу. Свойство НЕ ДОЛЖНО быть помечено одновременно как readOnly и writeOnly , являющееся true . Значение по умолчанию: false . xml XML-объект МОЖЕТ использоваться только в схемах свойств. Это не влияет на корневые схемы. Добавляет дополнительные метаданные для описания XML-представления этого свойства. внешние документы Объект внешней документации Дополнительная внешняя документация для этой схемы. пример Любой Свойство произвольной формы, включающее пример экземпляра для этой схемы. Чтобы представить примеры, которые не могут быть представлены естественным образом в JSON или YAML, можно использовать строковое значение, содержащее пример с экранированием, где это необходимо. устарело логическое значение Указывает, что схема устарела и ее СЛЕДУЕТ вывести из использования. Значение по умолчанию – 9.0639 ложь . Этот объект МОЖЕТ быть расширен за счет расширений спецификации. Состав и наследование (полиморфизм) Спецификация OpenAPI позволяет комбинировать и расширять определения моделей с использованием свойства allOf схемы JSON, фактически предлагая композицию модели. allOf принимает массив определений объектов, которые проверяются независимо, но вместе составляют один объект. Хотя композиция обеспечивает расширяемость модели, она не предполагает иерархии между моделями. Для поддержки полиморфизма спецификация OpenAPI добавляет дискриминатор поле. При использовании дискриминатор будет именем свойства, которое решает, какое определение схемы проверяет структуру модели. Таким образом, поле дискриминатора ДОЛЖНО быть обязательным полем. Есть два способа определить значение дискриминатора для наследуемого экземпляра. Используйте имя схемы. Переопределить имя схемы, заменив свойство новым значением. Если существует новое значение, оно имеет приоритет над именем схемы. Таким образом, встроенные определения схемы, которые не имеют заданного идентификатора, не может использоваться в полиморфизме. XML-моделирование Свойство xml позволяет использовать дополнительные определения при преобразовании определения JSON в XML. Объект XML содержит дополнительную информацию о доступных параметрах. Примеры объектов схемы Образец примитива { "тип": "строка", "формат": "электронная почта" } тип: строка формат: электронная почта Простая модель { "тип": "объект", "требуется": [ "имя" ], "характеристики": { "имя": { "тип": "строка" }, "адрес": { "$ref": "#/компоненты/схемы/адрес" }, "возраст": { "тип": "целое", "формат": "int32", "минимум": 0 } } } тип: объект требуется: - имя характеристики: имя: тип: строка адрес: $ref: '#/компоненты/схемы/адрес' возраст: тип: целое число формат: int32 минимум: 0 Модель со свойствами карты/словаря Для простого преобразования строки в строку: { "тип": "объект", "дополнительные свойства": { "тип": "строка" } } тип: объект дополнительные свойства: тип: строка Для сопоставления строки с моделью: { "тип": "объект", "дополнительные свойства": { "$ref": "#/компоненты/схемы/ComplexModel" } } тип: объект дополнительные свойства: $ref: '#/компоненты/схемы/ComplexModel' Модель с примером { "тип": "объект", "характеристики": { "я бы": { "тип": "целое", "формат": "int64" }, "имя": { "тип": "строка" } }, "требуется": [ "имя" ], "пример": { "имя": "Пума", "идентификатор": 1 } } тип: объект характеристики: я бы: тип: целое число формат: int64 имя: тип: строка требуется: - имя пример: имя: Пума идентификатор: 1 Модели с составом { "составные части": { "схемы": { "Модель ошибки": { "тип": "объект", "требуется": [ "сообщение", "код" ], "характеристики": { "сообщение": { "тип": "строка" }, "код": { "тип": "целое", "минимум": 100, "максимум": 600 } } }, "ExtendedErrorModel": { "все": [ { "$ref": "#/компоненты/схемы/ErrorModel" }, { "тип": "объект", "требуется": [ "первопричина" ], "характеристики": { "первопричина": { "тип": "строка" } } } ] } } } } компоненты: схемы: Модель ошибки: тип: объект требуется: - сообщение - код характеристики: сообщение: тип: строка код: тип: целое число минимум: 100 максимум: 600 Расширенная модель ошибки: все: - $ref: '#/components/schemas/ErrorModel' - тип: объект требуется: - первопричина характеристики: первопричина: тип: строка Модели с поддержкой полиморфизма { "составные части": { "схемы": { "Домашний питомец": { "тип": "объект", "дискриминатор": { "имя_свойства": "тип_питомца" }, "характеристики": { "имя": { "тип": "строка" }, "тип питомца": { "тип": "строка" } }, "требуется": [ "имя", "тип питомца" ] }, "Кошка": { "description": "Изображение кошки. Обратите внимание, что `Cat` будет использоваться в качестве значения дискриминатора.", "все": [ { "$ref": "#/компоненты/схемы/домашнее животное" }, { "тип": "объект", "характеристики": { "охотничий навык": { "тип": "строка", "description": "Измеренное умение для охоты", "по умолчанию": "ленивый", "перечисление": [ "невежественный", "ленивый", "авантюрный", "агрессивный" ] } }, "требуется": [ "охотничий навык" ] } ] }, "Собака": { "description": "Изображение собаки. Обратите внимание, что `Dog` будет использоваться в качестве значения дискриминатора.", "все": [ { "$ref": "#/компоненты/схемы/домашнее животное" }, { "тип": "объект", "характеристики": { "packSize": { "тип": "целое", "формат": "int32", "description": "размер стаи, из которой собака", "по умолчанию": 0, "минимум": 0 } }, "требуется": [ "Размер упаковки" ] } ] } } } } компоненты: схемы: Домашний питомец: тип: объект дискриминатор: имя свойства: petType характеристики: имя: тип: строка тип питомца: тип: строка требуется: - имя - тип питомца Cat: ## "Cat" будет использоваться как значение дискриминатора описание: Представление кота все: - $ref: '#/components/schemas/Pet' - тип: объект характеристики: охотничий навык: тип: строка описание: Измеренное умение для охоты перечисление: - невежественный - ленивый - предприимчивый - агрессивный требуется: - охотничье мастерство Собака: ## «Собака» будет использоваться в качестве значения дискриминатора. описание: изображение собаки все: - $ref: '#/components/schemas/Pet' - тип: объект характеристики: размер пакета: тип: целое число формат: int32 описание: размер стаи, из которой собака по умолчанию: 0 минимум: 0 требуется: - размер упаковки Объект-дискриминатор Если тело запроса или полезная нагрузка ответа могут представлять собой одну из нескольких различных схем, можно использовать объект-дискриминатор для облегчения сериализации, десериализации и проверки. Дискриминатор — это конкретный объект в схеме, который используется для информирования потребителя о спецификации альтернативной схемы на основе связанного с ней значения. При использовании дискриминатора встроенных схем не учитываются. Фиксированные поля Имя поля Тип Описание имя свойства струна ТРЕБУЕТСЯ . Имя свойства в полезных данных, которое будет содержать значение дискриминатора. отображение Карта [ строка , строка ] Объект для хранения сопоставлений между значениями полезной нагрузки и именами схем или ссылками. Объект дискриминатора допустим только при использовании одного из составных ключевых слов oneOf , anyOf , allOf . В OAS 3.0 полезная нагрузка ответа МОЖЕТ быть описана как ровно один из любого количества типов: MyResponseType: один из: - $ref: '#/components/schemas/Cat' - $ref: '#/компоненты/схемы/собака' - $ref: '#/components/schemas/Lizard' , что означает, что полезная нагрузка ДОЛЖНА при проверке соответствовать ровно одной из схем, описанных Кошка , Собака или Ящерица . В этом случае дискриминатор МОЖЕТ действовать как «подсказка» для быстрой проверки и выбора соответствующей схемы, что может быть дорогостоящей операцией, в зависимости от сложности схемы. Затем мы можем точно описать, какое поле говорит нам, какую схему использовать: MyResponseType: один из: - $ref: '#/components/schemas/Cat' - $ref: '#/компоненты/схемы/собака' - $ref: '#/components/schemas/Lizard' дискриминатор: имя свойства: petType Теперь ожидается, что свойство с именем petType ДОЛЖНО присутствовать в полезной нагрузке ответа , а его значение будет соответствовать имени схемы, определенной в документе OAS. Таким образом, полезная нагрузка ответа: { "идентификатор": 12345, "petType": "Кошка" } Указывает, что схема Cat должна использоваться вместе с этой полезной нагрузкой. В сценариях, где значение поля дискриминатора не соответствует имени схемы или неявное сопоставление невозможно, необязательный сопоставление определение МОЖЕТ использоваться: MyResponseType: один из: - $ref: '#/components/schemas/Cat' - $ref: '#/компоненты/схемы/собака' - $ref: '#/components/schemas/Lizard' - $ref: 'https://gigantic-server. com/schemas/Monster/schema.json' дискриминатор: имя свойства: petType сопоставление: собака: '#/компоненты/схемы/собака' монстр: 'https://gigantic-server.com/schemas/Monster/schema.json' Здесь значение дискриминатора из собака будет отображаться на схему #/components/schemas/Dog , а не на значение по умолчанию (неявное) Dog . Если значение дискриминатора не совпадает с неявным или явным сопоставлением, никакая схема не может быть определена, и проверка СЛЕДУЕТ завершиться ошибкой. Ключи сопоставления ДОЛЖНЫ быть строковыми значениями, но инструменты МОЖЕТ преобразовывать значения ответов в строки для сравнения. При использовании в сочетании с конструкцией anyOf использование дискриминатора позволяет избежать неоднозначности, когда несколько схем могут удовлетворять одной полезной нагрузке. В обоих вариантах использования oneOf и anyOf все возможные схемы ДОЛЖНЫ быть явно перечислены. Чтобы избежать избыточности, дискриминатор МОЖЕТ быть добавлен к определению родительской схемы, и все схемы, содержащие родительскую схему в конструкции allOf , могут использоваться в качестве альтернативной схемы. Например: компоненты: схемы: Домашний питомец: тип: объект требуется: - тип питомца характеристики: тип питомца: тип: строка дискриминатор: имя свойства: petType сопоставление: собака Собака Кошка: все: - $ref: '#/components/schemas/Pet' - тип: объект # все остальные свойства, характерные для `Cat` характеристики: имя: тип: строка Собака: все: - $ref: '#/components/schemas/Pet' - тип: объект # все остальные свойства, характерные для `Dog` характеристики: лаять: тип: строка Ящерица: все: - $ref: '#/components/schemas/Pet' - тип: объект # все остальные свойства, специфичные для `Lizard` характеристики: любитRocks: тип: логический такая полезная нагрузка: { "petType": "Кошка", "имя": "туманный" } будет означать, что используется схема Cat . Аналогично этой схеме: { "petType": "собака", «кора»: «мягкая» } будет отображаться в Dog из-за определения в элементе mappings . Объект XML Объект метаданных, который позволяет более точно настроить определения модели XML. При использовании массивов имена элементов XML равны , а не (для форм единственного/множественного числа), и свойство имя СЛЕДУЕТ использовать для добавления этой информации. См. примеры ожидаемого поведения. Фиксированные поля Имя поля Тип Описание имя струна Заменяет имя элемента/атрибута, используемого для описываемого свойства схемы. Когда он определен в элементах , это повлияет на имена отдельных элементов XML в списке. При определении рядом с тип , являющийся массивом (вне элементов ), это повлияет на элемент упаковки, и только если обернутый равен true . Если обернутый равен false , он будет проигнорирован. пространство имен струна URI определения пространства имен. Значение ДОЛЖНО быть в форме абсолютного URI. префикс струна Префикс для имени. атрибут логическое значение Указывает, преобразуется ли определение свойства в атрибут, а не в элемент. Значение по умолчанию: false . в упаковке логическое значение МОЖЕТ использоваться только для определения массива. Указывает, является ли массив упакованным (например, ) или развернутым ( ). Значение по умолчанию: false . Определение вступает в силу только в том случае, если оно определено рядом с типом , являющимся массивом (вне элементов ). Этот объект МОЖЕТ быть расширен за счет расширений спецификации. Примеры XML-объектов Примеры определений XML-объектов включены в определение свойства объекта схемы с образцом его XML-представления. Нет XML-элемента Свойство основной строки: { "животные": { "тип": "строка" } } животных: тип: строка <животные>... Основное свойство массива строк ( в оболочке по умолчанию false ): { "животные": { "тип": "массив", "Предметы": { "тип": "строка" } } } животных: тип: массив Предметы: тип: строка <животные>... <животные>... <животные>... Замена имени XML { "животные": { "тип": "строка", "xml": { "имя": "животное" } } } животных: тип: строка XML: имя: животное <животное>. .. XML-атрибут, префикс и пространство имен В этом примере показано полное определение модели. { "Человек": { "тип": "объект", "характеристики": { "я бы": { "тип": "целое", "формат": "int32", "xml": { "атрибут": правда } }, "имя": { "тип": "строка", "xml": { "пространство имен": "http://example.com/schema/sample", "префикс": "образец" } } } } } Лицо: тип: объект характеристики: я бы: тип: целое число формат: int32 XML: атрибут: правда имя: тип: строка XML: пространство имен: http://example.com/schema/sample префикс: образец <Лицо> пример Массивы XML Изменение имен элементов: { "животные": { "тип": "массив", "Предметы": { "тип": "строка", "xml": { "имя": "животное" } } } } животных: тип: массив Предметы: тип: строка XML: имя: животное <животное>значение <животное>значение Внешнее свойство name не влияет на XML: { "животные": { "тип": "массив", "Предметы": { "тип": "строка", "xml": { "имя": "животное" } }, "xml": { "имя": "инопланетяне" } } } животных: тип: массив Предметы: тип: строка XML: имя: животное XML: Название: пришельцы <животное>значение <животное>значение Даже если массив упакован, если имя не определено явно, одно и то же имя будет использоваться как внутри, так и снаружи: { "животные": { "тип": "массив", "Предметы": { "тип": "строка" }, "xml": { "завернутый": правда } } } животных: тип: массив Предметы: тип: строка XML: завернутый: правда <животные> <животные>значение <животные>значение Чтобы решить проблему именования в приведенном выше примере, можно использовать следующее определение: { "животные": { "тип": "массив", "Предметы": { "тип": "строка", "xml": { "имя": "животное" } }, "xml": { "завернутый": правда } } } животных: тип: массив Предметы: тип: строка XML: имя: животное XML: завернутый: правда <животные> <животное>значение <животное>значение Влияет как на внутренние, так и на внешние имена: { "животные": { "тип": "массив", "Предметы": { "тип": "строка", "xml": { "имя": "животное" } }, "xml": { "имя": "инопланетяне", "завернутый": правда } } } животных: тип: массив Предметы: тип: строка XML: имя: животное XML: Название: пришельцы завернутый: правда <инопланетяне> <животное>значение <животное>значение Если мы изменим внешний элемент, но не внутренние: { "животные": { "тип": "массив", "Предметы": { "тип": "строка" }, "xml": { "имя": "инопланетяне", "завернутый": правда } } } животных: тип: массив Предметы: тип: строка XML: Название: пришельцы завернутый: правда <инопланетяне> <инопланетяне>значение <инопланетяне>значение Объект схемы безопасности Определяет схему безопасности, которую могут использовать операции. Поддерживаемые схемы: HTTP-аутентификация, ключ API (в виде заголовка, параметра cookie или параметра запроса), общие потоки OAuth3 (неявные, пароль, учетные данные клиента и код авторизации), как определено в RFC6749, и OpenID Connect Discovery. Фиксированные поля Имя поля Тип Применяется к Описание тип струна Любой ТРЕБУЕТСЯ . Тип схемы безопасности. Допустимые значения: "apiKey" , "http" , "oauth3" , "openIdConnect" . описание струна Любой Краткое описание схемы безопасности. Синтаксис CommonMark МОЖЕТ использоваться для форматированного текстового представления. имя струна ключ API ТРЕБУЕТСЯ . Имя используемого заголовка, запроса или файла cookie. в струна ключ API ТРЕБУЕТСЯ . Расположение ключа API. Допустимые значения: "запрос" , "заголовок" или "cookie" . схема струна http ТРЕБУЕТСЯ . Имя схемы авторизации HTTP, которая будет использоваться в заголовке авторизации, как определено в RFC7235. Используемые значения СЛЕДУЕТ зарегистрировать в реестре IANA Authentication Scheme. форма носителя струна http ( "носитель" ) Подсказка клиенту определить, как отформатирован маркер носителя. Токены-носители обычно генерируются сервером авторизации, поэтому эта информация предназначена в первую очередь для целей документации. потоки Объект потоков OAuth оаут3 ТРЕБУЕТСЯ . Объект, содержащий информацию о конфигурации для поддерживаемых типов потока. опенидконнектурл струна опенидконнект ТРЕБУЕТСЯ . URL-адрес OpenId Connect для обнаружения значений конфигурации OAuth3. Это ДОЛЖНО быть в форме URL. Этот объект МОЖЕТ быть расширен за счет расширений спецификации. Пример объекта схемы безопасности Пример базовой аутентификации { "тип": "http", "схема": "базовая" } тип: http схема: базовая Образец ключа API { "тип": "апиКей", "имя": "api_key", "в": "заголовок" } тип: APIKey имя: API_key в: заголовок Образец носителя JWT { "тип": "http", "схема": "носитель", "bearerFormat": "JWT", } тип: http схема: носитель носительФормат: JWT Неявный образец OAuth3 { "тип": "oauth3", "течет": { "скрытый": { "authorizationUrl": "https://example. com/api/oauth/dialog", "области": { "write:pets": "изменить питомцев в вашем аккаунте", "read:pets": "читать своих питомцев" } } } } тип: oauth3 потоки: скрытый: URL-адрес авторизации: https://example.com/api/oauth/dialog области: write:pets: изменить питомцев в своей учетной записи read:pets: читай своих питомцев Объект потоков OAuth Позволяет настраивать поддерживаемые потоки OAuth. Фиксированные поля Имя поля Тип Описание неявный Объект потока OAuth Конфигурация для неявного потока OAuth пароль Объект потока OAuth Конфигурация для потока пароля владельца ресурса OAuth учетные данные клиента Объект потока OAuth Конфигурация потока учетных данных клиента OAuth. Ранее называвшееся приложением в OpenAPI 2. 0. Код авторизации Объект потока OAuth Конфигурация потока кода авторизации OAuth. Ранее назывался accessCode в OpenAPI 2.0. Этот объект МОЖЕТ быть расширен за счет расширений спецификации. Объект потока OAuth Сведения о конфигурации для поддерживаемого потока OAuth Фиксированные поля Имя поля Тип Применяется к Описание URL авторизации струна oauth3 ( "неявный" , "код авторизации" ) ТРЕБУЕТСЯ . URL-адрес авторизации, который будет использоваться для этого потока. Это ДОЛЖНО быть в форме URL. tokenUrl струна oauth3 ( "пароль" , "учетные данные клиента" , "код авторизации" ) ТРЕБУЕТСЯ . URL-адрес токена, который будет использоваться для этого потока. Это ДОЛЖНО быть в форме URL. URL-адрес обновления струна оаут3 URL-адрес, используемый для получения токенов обновления. Это ДОЛЖНО быть в форме URL. прицелы Карта [ строка , строка ] оаут3 ТРЕБУЕТСЯ . Доступные области для схемы безопасности OAuth3. Сопоставление между именем области действия и ее кратким описанием. Карта МОЖЕТ быть пустой. Этот объект МОЖЕТ быть расширен за счет расширений спецификации. Примеры объектов потока OAuth { "тип": "oauth3", "течет": { "скрытый": { "authorizationUrl": "https://example.com/api/oauth/dialog", "области": { "write:pets": "изменить питомцев в вашем аккаунте", "read:pets": "читать своих питомцев" } }, "Код авторизации": { "authorizationUrl": "https://example. com/api/oauth/dialog", "tokenUrl": "https://example.com/api/oauth/токен", "области": { "write:pets": "изменить питомцев в вашем аккаунте", "read:pets": "читать своих питомцев" } } } } тип: oauth3 потоки: скрытый: URL-адрес авторизации: https://example.com/api/oauth/dialog области: write:pets: изменить питомцев в своей учетной записи read:pets: читай своих питомцев Код авторизации: URL-адрес авторизации: https://example.com/api/oauth/dialog tokenUrl: https://example.com/api/oauth/token области: write:pets: изменить питомцев в своей учетной записи read:pets: читай своих питомцев Security Requirement Object Список необходимых схем безопасности для выполнения этой операции. Имя, используемое для каждого свойства, ДОЛЖНО соответствовать схеме безопасности, объявленной в схемах безопасности в объекте компонентов. Security Requirement Объекты, которые содержат несколько схем, требуют, чтобы все схемы ДОЛЖНЫ быть удовлетворены для авторизации запроса. Это обеспечивает поддержку сценариев, в которых для передачи информации о безопасности требуется несколько параметров запроса или заголовков HTTP. Когда список объектов требований безопасности определен для объекта OpenAPI или объекта операции, только один из объектов требований безопасности в списке должен быть удовлетворен для авторизации запроса. узорчатых поля Полевой узор Тип Описание {имя} [ строка ] Каждое имя ДОЛЖНО соответствовать схеме безопасности, которая объявлена ​​в схемах безопасности в объекте компонентов. Если схема безопасности имеет тип "oauth3" или "openIdConnect" , то значение представляет собой список имен областей, необходимых для выполнения, и этот список МОЖЕТ быть пустым, если для авторизации не требуется указанная область. Для других типов схем безопасности массив ДОЛЖЕН быть пустым. Примеры объектов требования безопасности Требование безопасности без OAuth3 { "апи_ключ": [] } API_key: [] Требование безопасности OAuth3 { "зоомагазин_аутент": [ "написать: домашние животные", "читать: домашние животные" ] } petstore_auth: - напиши: домашние животные - читать: домашние животные Дополнительная безопасность OAuth3 Дополнительная безопасность OAuth3, определенная в объекте OpenAPI или объекте операции: { "безопасность": [ {}, { "зоомагазин_аутент": [ "написать: домашние животные", "читать: домашние животные" ] } ] } служба безопасности: - {} - petstore_auth: - напиши: домашние животные - читать: домашние животные Расширения спецификации Несмотря на то, что спецификация OpenAPI пытается приспособить большинство вариантов использования, в определенные моменты могут быть добавлены дополнительные данные для расширения спецификации. Свойства расширений реализованы в виде шаблонных полей, которые всегда имеют префикс "x-" . 9х- Полевая модель Тип Описание Любой Разрешает расширения схемы OpenAPI. Имя поля ДОЛЖНО начинаться с x-, например, x-internal-id . Значение может быть null , примитивом, массивом или объектом. Может иметь любое допустимое значение формата JSON. Расширения могут поддерживаться или не поддерживаться доступными инструментами, но они также могут быть расширены для добавления запрошенной поддержки (если инструменты являются внутренними или открытыми). Безопасность Фильтрация Некоторые объекты в спецификации OpenAPI МОГУТ быть объявлены и оставаться пустыми или быть полностью удалены, даже если они по своей сути являются ядром документации API. Причина в том, чтобы обеспечить дополнительный уровень контроля доступа к документации. Хотя это и не является частью самой спецификации, некоторые библиотеки МОГУТ разрешать доступ к частям документации на основе той или иной формы аутентификации/авторизации. Два примера: Объект Paths МОЖЕТ быть пустым. Это может показаться нелогичным, но это может сказать зрителю, что он попал в нужное место, но не может получить доступ к какой-либо документации. У них по-прежнему будет доступ к информационному объекту, который может содержать дополнительную информацию об аутентификации. Объект элемента пути МОЖЕТ быть пустым. В этом случае зритель будет знать, что путь существует, но не сможет увидеть какие-либо его операции или параметры. Это отличается от сокрытия самого пути от объекта Paths, потому что пользователь будет знать о его существовании. Это позволяет поставщику документации точно контролировать то, что может видеть зритель. Приложение A: История изменений Версия Дата Примечания 3. 0.3 20.02.2020 Выпуск исправления спецификации OpenAPI 3.0.3 3.0.2 08.10.2018 Выпуск исправления спецификации OpenAPI 3.0.2 3.0.1 06.12.2017 Выпуск исправления спецификации OpenAPI 3.0.1 3.0.0 26.07.2017 Выпуск спецификации OpenAPI 3.0.0 3.0.0-rc2 16.06.2017 rc2 спецификации 3.0 3.0.0-rc1 27.04.2017 rc1 спецификации 3.0 3.0.0-rc0 28.02.2017 Проект реализации спецификации 3.0 2,0 31.12.2015 Пожертвование Swagger 2.0 инициативе OpenAPI 2,0 08.09.2014 Выпуск Swagger 2.0 1,2 14.03.2014 Первоначальный выпуск официального документа. 1,1 22 августа 2012 г. Выпуск Swagger 1.1 1,0 10.08.2011 Первый выпуск спецификации Swagger Таблица для формирования | Дизайнер форм | Руководство пользователя | Epi Info™ Как сделать форму из таблицы данных Функция «Создать форму из таблицы данных» позволяет автоматически создавать форму Epi Info™ 7 на основе существующего файла базы данных. После завершения у вас будет первоначальная структура формы, которую при необходимости можно изменить. Типы полей, справочные таблицы кодов и подсказки полей могут быть указаны во время процесса. Поддерживаемые форматы включают MS Excel, MS Access, Flat ASCII, SQL Server и MySQL среди других типов. Допустим, у вас есть электронная таблица Excel с данными, которые вы исторически поддерживали с помощью MS Excel, но хотели бы создать проект Epi Info для сбора данных и воспользоваться преимуществами, которые можно получить от ввода данных с помощью Epi Info. 7. Эта функция позволяет пользователям делать это. На первом этапе вам потребуется создать проект Epi Info™ 7. При запросе имени формы назначьте любое имя форме. В конечном итоге форма будет удалена после завершения процесса импорта из файла MS Excel. В главном меню Epi Info выберите Utilities > Make Form from Data Table . Откроется диалоговое окно «Создать форму из таблицы ». Выберите нужный тип базы данных. В этом примере мы выберем рабочую книгу Microsoft MS Excel 97-2003. Перейдите к местоположению файла. Щелкните имя электронной таблицы, содержащей набор данных, который вы хотите импортировать в Epi Info™ 7. Укажите имя формы. Щелкните OK . Откроется диалоговое окно Table-to-Form . Отображается ряд столбцов. Нажмите Установить шрифт подсказки и Установить шрифт поля , чтобы установить шрифты для вопросов/подсказок и полей ввода соответственно. Если какой-либо из столбцов в исходной таблице должен стать типом поля Допустимое значение, щелкните Добавить исходную таблицу списка и найдите таблицу, содержащую список допустимых значений. Это понадобится ниже для Столбец ListSourceTableName . Вот описание каждого столбца: Импорт — этот флажок позволяет выбрать, какие поля следует импортировать в форму, и отключить импорт для других полей. По умолчанию отмечены все поля. Имя столбца — указывает имя столбца из исходной таблицы. Имя столбца изначально используется для имени поля и подсказки. Имя поля — Имя поля изначально совпадает с именем столбца, но вы можете изменить его сейчас здесь или позже, посетив свойства поля после создания формы. Если имя поля является зарезервированным словом Epi Info, процесс Table-to-Form автоматически изменит его, добавив суффикс «_RW». Вы можете изменить это имя на что-то более релевантное. Подсказка — Подсказка изначально совпадает с именем поля. Вы можете изменить его сейчас здесь или позже, посетив свойства поля. Тип столбца — это тип данных, обнаруженных Epi Info™ 7. Тип поля — указывает тип поля, который, вероятно, соответствует типу столбца. Например, если Epi Info™ 7 обнаружит строковые данные для типа столбца, то он предложит тип поля для хранения этих данных может быть текстовым полем. Вы можете отменить это решение, если знаете, что представляют собой данные. Например, если столбец содержит только значения «Да» и «Нет», Epi Info™ может предложить поле «Текст», но вы можете решить, что тип поля «Да-Нет» является более подходящим. Страница – Для таблиц с большим количеством столбцов Epi Info™ будет размещать поля в форме в соответствии с порядком их появления в исходной таблице. Он будет складывать столько полей, сколько поместится на первой странице, затем будет продолжать добавлять страницы и поля стека по мере необходимости, чтобы разместить все столбцы. Вы можете использовать столбец «Страница», чтобы дать указание Epi Info™ хранить определенные поля вместе на определенной странице. Примечание. На любой странице существует ограничение примерно в 250 полей. Вкладка — определяет порядок полей на странице во время ввода данных. Табуляция — если для поля будут вводиться данные, этот флажок должен оставаться отмеченным. Некоторые поля рассчитываются автоматически, поэтому для них не требуется позиция табуляции, и поэтому флажок «Позиция табуляции» должен быть снят. Когда флажок Tab Stop снят, курсор не будет перемещаться в поле во время ввода данных. Только чтение — этот флажок устанавливает атрибут поля Только чтение. Если флажок установлен, поле будет отключено. По умолчанию он не отмечен. Обязательный — Поля, в которых ввод данных является обязательным, должны иметь этот обязательный атрибут. По умолчанию он не отмечен. Повторить последнюю — если этот флажок установлен, атрибут «Повторять последнюю» приводит к тому, что значение последней просматриваемой записи становится предварительно заполненным значением при создании новой записи. По умолчанию он не отмечен. Диапазон — позволяет указать указанное значение между одним значением и другим. Если во время ввода данных вы попытаетесь ввести значение, выходящее за пределы указанного диапазона, вы получите предупреждающее сообщение о том, что значение находится вне диапазона. Отсутствующие значения принимаются. По умолчанию он не отмечен. Если вы установите флажок Диапазон, то также укажите нижний и верхний диапазоны, как описано ниже. Нижний — Укажите наименьшее значение, которое можно ввести в поле. Верхний — Укажите наибольшее или максимальное значение, которое может быть принято полем. Имя исходной таблицы списка — если справочная таблица была импортирована с использованием параметра «Добавить исходную таблицу списка», поле можно связать с одной из импортированных таблиц. Это относится только к полям Legal Value. Имя столбца исходного текста списка — если в импортированной справочной таблице доступно более одного столбца, укажите, какое имя столбца следует использовать для сопоставления с полем из таблицы. Исходная таблица списка — поля можно удалить из списка полей просмотра с помощью одинарной или двойной стрелки назад. Нажмите Преобразовать , чтобы начать процесс импорта. Начинается процесс создания формы и импорта процесса. После завершения процесса появится сообщение «Процесс импорта таблицы в форму завершен».   После завершения процесса импорта в форму можно внести некоторые изменения, такие как выравнивание, шрифт и добавление меток и заголовков. Однако не копируйте и не вставляйте поля с одной страницы на другую. Если вы намерены перемещать поля по страницам после импорта, мы настоятельно рекомендуем вам сначала удалить таблицы данных, не удаляя форму, переместить поля на нужные страницы, а затем использовать команду MERGE в Classic Analysis для объединения данных в исправленную форму. . Как найти или проверить адрес электронной почты Регулярное выражение, о котором я получаю больше всего отзывов, не говоря уже об отчетах об ошибках, это то, которое вы найдете прямо на главной странице этого сайта: \b[A-Z0 -9. _%+-]+@[A-Z0-9.-]+\.[A-Z]{2,}\b. Я утверждаю, что это регулярное выражение соответствует любому адресу электронной почты. Большинство отзывов, которые я получаю, опровергают это утверждение, показывая один адрес электронной почты, которому это регулярное выражение не соответствует. Обычно отчет об «ошибке» также включает предложение сделать регулярное выражение «идеальным». Как я объясню ниже, мое утверждение справедливо только в том случае, если вы принимаете мое определение того, что действительно является действительным адресом электронной почты, а что нет. Если вы хотите использовать другое определение, вам придется адаптировать регулярное выражение. Сопоставление действительного адреса электронной почты — прекрасный пример, показывающий, что (1) прежде чем писать регулярное выражение, вы должны точно знать, что вы пытаетесь сопоставить, а что нет; и (2) часто приходится идти на компромисс между тем, что точно, и тем, что практично. Преимущество моего регулярного выражения в том, что оно соответствует 99% адресов электронной почты, используемых сегодня. Все совпадающие адреса электронной почты могут быть обработаны 99% всего программного обеспечения электронной почты. Если вы ищете быстрое решение, вам нужно прочитать только следующий абзац. Если вы хотите узнать обо всех компромиссах и получить множество альтернатив на выбор, читайте дальше. Если вы хотите использовать приведенное выше регулярное выражение, вам нужно понять две вещи. Во-первых, длинные регулярные выражения затрудняют красивое форматирование абзацев. Поэтому я не включил az ни в один из трех классов символов. Это регулярное выражение предназначено для использования с включенной опцией «без учета регистра» вашего движка регулярных выражений. (Вы будете удивлены, сколько отчетов об ошибках я получаю по этому поводу.) Во-вторых, приведенное выше регулярное выражение ограничено границами слов, что делает его пригодным для извлечения адресов электронной почты из файлов или больших блоков текста. Если вы хотите проверить, ввел ли пользователь действительный адрес электронной почты, замените границы слов якорями начала и конца строки, например: ^[A-Z0-9. _%+-]+@[A-Z0-9.-]+\.[A-Z]{2,}$. Предыдущий абзац также относится ко всем следующим примерам. Возможно, вам потребуется изменить границы слов на якоря начала/конца строки или наоборот. И вы должны включить опцию соответствия без учета регистра. Компромиссы при проверке адресов электронной почты До того, как ICANN предоставила любой хорошо финансируемой компании возможность создавать свои собственные домены верхнего уровня, самыми длинными доменами верхнего уровня были редко используемые .museum и .travel, которые состоят из 6 букв. длинная. Наиболее распространенные домены верхнего уровня имели длину 2 буквы для доменов для конкретной страны и 3 или 4 буквы для доменов общего назначения, таких как .com и .info. Многие регулярные выражения для проверки адресов электронной почты, которые вы найдете в различных руководствах и справочниках по регулярным выражениям, по-прежнему предполагают, что домен верхнего уровня довольно короткий. В более ранних выпусках этого руководства по регулярным выражениям упоминалось \b[A-Z0-9. _%+-]+@[A-Z0-9.-]+\.[A-Z]{2,4}\b в качестве регулярного выражения для адресов электронной почты во введении. Между этим регулярным выражением и тем, что вверху этой страницы, есть только одно небольшое отличие. 4 в конце регулярного выражения ограничивает домен верхнего уровня 4 символами. Если вы используете это регулярное выражение с якорями для проверки адреса электронной почты, введенного в форму заказа, [email protected] должен делать покупки в другом месте. Да, TLD .solutions существует, и когда я пишу это, disapproved.solutions может стать вашим за 16,88 долларов в год. 9[A-Z0-9._%+-]+@[A-Z0-9.-]+\.[A-Z]{2,63}$ — это то, на что вы практически способны. Каждая часть доменного имени не может быть длиннее 63 символов. Однозначных доменов верхнего уровня не существует, и ни один из них не содержит цифр. Не похоже, что ICANN также одобрит такие домены. Адреса электронной почты могут находиться на серверах в субдомене, например [email protected]. Все приведенные выше регулярные выражения соответствуют этому адресу электронной почты, потому что я поставил точку в классе символов после символа @. Но приведенные выше регулярные выражения также соответствуют [email protected], что недопустимо из-за последовательных точек. Вы можете исключить такие совпадения, заменив [A-Z0-9[A-Z0-9._%+-]{1,64}@(?:[A-Z0-9-]{1,63}\.){1,125}[A-Z]{2,63}$ занимает принимая во внимание, что локальная часть (перед @) ограничена 64 символами и что каждая часть доменного имени ограничена 63 символами. Прямого ограничения на количество поддоменов нет. Но максимальная длина адреса электронной почты, который может обрабатываться SMTP, составляет 254 символа. Таким образом, с односимвольной локальной частью, двухбуквенным доменом верхнего уровня и односимвольными поддоменами 125 — это максимальное количество поддоменов. Предыдущее регулярное выражение на самом деле не ограничивает адреса электронной почты 254 символами. Если каждая часть имеет максимальную длину, регулярное выражение может сопоставлять строки длиной до 8129 символов. Вы можете уменьшить это количество, уменьшив количество разрешенных субдоменов со 125 до чего-то более реалистичного, например, 8. [A-Z0-9(?=[A-Z0-9][A-Z0-9@._%+-]{5,253}$) [A-Z0-9._%+-]{1,64}@(?: [A-Z0-9-]{1,63}\.){1,8}[A-Z]{2,63}$ Доменные имена могут содержать дефисы. Но они не могут начинаться или заканчиваться дефисом. [A-Z0-9](?:[A-Z0-9-]{0,62}[A-Z0-9])? соответствует доменному имени длиной от 1 до 63 символов, которое начинается и заканчивается буквой или цифрой. Незахватывающая группа делает середину домена и последнюю букву или цифру необязательными в целом, чтобы гарантировать, что мы разрешаем односимвольные домены, в то же время гарантируя, что домены с двумя или более символами не заканчиваются дефисом. Общее регулярное выражение становится довольно сложным: 9[A-Z0-9][A-Z0-9._%+-]{0,63}@ (?:[A-Z0-9](?:[A-Z0-9-]{0, 62}[A-Z0-9])?\.){1,8}[A-Z]{2,63}$ Доменные имена не могут содержать дефисы подряд. [A-Z0-9]+(?:-[A-Z0-9]+)* соответствует доменному имени, которое начинается и заканчивается буквой или цифрой и содержит любое количество не следующих друг за другом дефисов. Это самый эффективный способ. Это регулярное выражение не выполняет поиск с возвратом для соответствия допустимому доменному имени. Он соответствует всем буквам и цифрам в начале имени домена. Если дефисов нет, следующая необязательная группа немедленно завершается ошибкой. Если есть дефисы, группа соответствует каждому дефису, за которым следуют все буквы и цифры до следующего дефиса или конца доменного имени. Мы не можем установить максимальную длину, когда дефис должен быть в паре с буквой или цифрой, но буквы и цифры могут стоять сами по себе. Но мы можем использовать метод упреждающего просмотра, который мы использовали для принудительной установки общей длины адреса электронной почты, чтобы обеспечить длину доменного имени и запретить последовательные дефисы: (?=[A-Z0-9-]{1,63}\.)[A-Z0-9]+(?:-[A-Z0-9]+)*. Обратите внимание, что просмотр вперед также проверяет наличие точки, которая должна стоять после доменного имени, если оно полностью определено в адресе электронной почты. Это важно. Без проверки точки поиск вперед будет принимать более длинные доменные имена. Поскольку поиск вперед не использует текст, которому он соответствует, точка не включается в общее совпадение этого регулярного выражения. Когда мы поместим это регулярное выражение в общее регулярное выражение для адресов электронной почты, точка будет соответствовать тому, что было в предыдущих регулярных выражениях: 9(?=[A-Z0-9][A-Z0-9@._%+-]{5,253}$)[A-Z0-9._%+-]{1,64}@ (?: (?=[A-Z0-9-]{1,63}\.)[A-Z0-9]+(?:-[A-Z0-9]+)*\.){1,8}[ A-Z]{2,63}$ На современном ПК или сервере это регулярное выражение отлично работает при проверке одного 254-символьного адреса электронной почты. Отклонение более длинных входных данных было бы даже быстрее, потому что регулярное выражение завершится ошибкой, если просмотр вперед завершится ошибкой во время первого прохода. Но я бы не рекомендовал использовать такое сложное регулярное выражение для поиска адресов электронной почты в большом архиве документов или корреспонденции. Вам лучше использовать простое регулярное выражение в верхней части этой страницы, чтобы быстро собрать все, что похоже на адрес электронной почты. [A-Z0-9(?=[A-Z0-9][A-Z0-9@._%+-]{5,253}+$)[A-Z0-9._%+-]{1,64}+@ ( ?:(?=[A-Z0-9-]{1,63}+\.)[A-Z0-9]++(?:-[A-Z0-9]++)*+\.) {1,8}+[A-Z]{2,63}+$ Важным компромиссом во всех этих регулярных выражениях является то, что они позволяют использовать только английские буквы, цифры и наиболее часто используемые специальные символы. Основная причина в том, что я не верю, что все мои почтовые программы способны справиться с чем-то еще. Несмотря на то, что John.O'[email protected] является синтаксически допустимым адресом электронной почты, существует риск того, что некоторые программы неправильно интерпретируют апостроф как разделительную кавычку. Слепая вставка этого адреса электронной почты в SQL-запрос, например, в лучшем случае приведет к сбою, когда строки заключены в одинарные кавычки, а в худшем случае откроет ваш сайт для атак SQL-инъекций. И, конечно же, доменные имена уже много лет могут содержать неанглийские символы. Но большая часть программного обеспечения по-прежнему придерживается 37 символов, к которым привыкли западные программисты. Поддержка интернационализированных доменов открывает целую банку червей в отношении того, как следует кодировать символы, отличные от ASCII. Поэтому, если вы используете любое из регулярных выражений на этой странице, любому, у кого есть адрес @ทีเอชนิค.ไทย, не повезет. Но, возможно, это говорит о том, что http://ทีเอชนิค.ไทย просто перенаправляет на http://thnic.co.th, хотя они занимаются продажей доменов .ไทย. Вывод таков: чтобы решить, какое регулярное выражение использовать, пытаетесь ли вы сопоставить адрес электронной почты или что-то еще, что определено нечетко, вам нужно начать с рассмотрения всех компромиссов. Насколько плохо сопоставлять что-то, что недействительно? Насколько плохо не соответствовать чему-то действительному? Насколько сложным может быть ваше регулярное выражение? Насколько дорого это обойдется, если вам придется изменить регулярное выражение позже, потому что оно окажется слишком широким или слишком узким? Различные ответы на эти вопросы потребуют различных регулярных выражений в качестве решения. Мое регулярное выражение электронной почты делает то, что я хочу, но может не делать то, что вы хотите. Регулярные выражения не отправляют электронную почту Не переусердствуйте, пытаясь устранить недопустимые адреса электронной почты с помощью регулярного выражения. Причина в том, что вы на самом деле не знаете, действителен ли адрес, пока не попытаетесь отправить на него электронное письмо. И даже этого может быть недостаточно. Даже если электронное письмо приходит в почтовый ящик, это не значит, что кто-то все еще читает этот ящик. Если вам действительно нужно убедиться, что адрес электронной почты действителен, вам необходимо отправить на него электронное письмо, содержащее код или ссылку для выполнения получателем второго шага аутентификации. И если вы делаете это, то нет смысла использовать регулярное выражение, которое может отклонить действительные адреса электронной почты. Тот же принцип применяется во многих ситуациях. При попытке сопоставить действительную дату часто проще использовать арифметические действия для проверки високосных лет, чем пытаться сделать это в регулярном выражении. Используйте регулярное выражение, чтобы найти возможные совпадения, или проверьте, использует ли ввод правильный синтаксис, и выполните фактическую проверку потенциальных совпадений, возвращаемых регулярным выражением. Регулярные выражения — мощный инструмент, но далеко не панацея. Официальный стандарт: RFC 5322 Возможно, вам интересно, почему не существует «официального» надежного регулярного выражения для сопоставления адресов электронной почты. Ну, есть официальное определение, но вряд ли оно надежное. Официальный стандарт известен как RFC 5322. Он описывает синтаксис, которого должны придерживаться действительные адреса электронной почты. Вы можете (но не должны — читайте дальше) реализовать это с помощью следующего регулярного выражения. RFC 5322 оставляет часть имени домена открытой для конкретных вариантов реализации, которые сегодня не будут работать в Интернете. Регулярное выражение реализует «предпочтительный» синтаксис из RFC 1035, который является одной из рекомендаций в RFC 5322: 9_‘{|}~-]+)*  | "(?:[\x01-\x08\x0b\x0c\x0e-\x1f\x21\x23-\x5b\x5d-\x7f]       |  \\[\x01-\x09\x0b\x0c\x0e-\ x7f])*") @ (?:(?:[a-z0-9](?:[a-z0-9-]*[a-z0-9])?\. )+[a-z0 -9](?:[a-z0-9-]*[a-z0-9])?   |  \[(?:(?:25[0-5]|2[0-4][0- 9]|[01]?[0–9][0–9]?)\.){3}        (?:25[0–5]|2[0–4][0–9]|[01 ]?[0-9][0-9]?|[a-z0-9-]*[a-z0-9]:           (?:[\x01-\x08\x0b\x0c\x0e-\x1f \x21-\x5a\x53-\x7f]           |  \\[\x01-\x09\x0b\x0c\x0e-\x7f])+)      \])\z Это регулярное выражение состоит из двух частей: часть до @ и часть после @. Есть две альтернативы для части перед @. Первый вариант позволяет ему состоять из ряда букв, цифр и определенных символов, включая одну или несколько точек. Однако точки могут не появляться последовательно или в начале или в конце адреса электронной почты. Другой вариант требует, чтобы часть перед @ была заключена в двойные кавычки, позволяя любую строку символов ASCII между кавычками. Символы пробела, двойные кавычки и обратные косые черты должны быть экранированы обратными косыми чертами. Часть после символа @ также имеет два варианта. Это может быть либо полное доменное имя (например, регулярные-выражения. info), либо буквальный интернет-адрес в квадратных скобках. Буквальный интернет-адрес может быть либо IP-адресом, либо адресом маршрутизации для конкретного домена. Причина, по которой вам не следует использовать это регулярное выражение, заключается в том, что оно слишком широкое. Ваше приложение может не поддерживать все адреса электронной почты, разрешенные этим регулярным выражением. Адреса маршрутизации для конкретного домена могут содержать непечатаемые управляющие символы ASCII, что может вызвать проблемы, если вашему приложению необходимо отображать адреса. Не все приложения поддерживают синтаксис локальной части с использованием двойных кавычек или квадратных скобок. Фактически, сам RFC 5322 помечает нотацию с использованием квадратных скобок как устаревшую. 9_'{|}~-]+)*@ (?:[a-z0-9](?:[a-z0-9-]*[a-z0-9])?\.)+[a -z0-9](?:[a-z0-9-]*[a-z0-9])?\z Ни одно из этих регулярных выражений не налагает ограничений на длину всего адреса электронной почты, локальной части или доменных имен. . RFC 5322 не устанавливает ограничений по длине. Это связано с ограничениями других протоколов, таких как протокол SMTP, для фактической отправки электронной почты. В RFC 1035 указано, что длина домена не должна превышать 63 символа, но это не включено в спецификацию синтаксиса. Причина в том, что настоящий регулярный язык не может одновременно применять ограничение длины и запрещать последовательные дефисы. Но современные разновидности регулярных выражений не совсем регулярны, поэтому мы можем добавить проверки ограничения длины с помощью упреждающего просмотра, как мы делали раньше: 9_'{|}~-]+)* @ (?:(?=[a-z0-9-]{1,63}\.)[a-z0-9](?:[a-z0- 9-]*[a-z0-9])?\.)+   (?=[a-z0-9-]{1,63}\z)[a-z0-9](?:[a- z0-9-]*[a-z0-9])?\z Таким образом, даже при следовании официальным стандартам приходится идти на компромиссы. Не копируйте слепо регулярные выражения из онлайн-библиотек или дискуссионных форумов. Всегда проверяйте их на собственных данных и в своих приложениях. | Быстрый старт | Учебник | Инструменты и языки | Примеры | Ссылка | Обзоры книг | | Примеры регулярных выражений | Числовые диапазоны | Числа с плавающей запятой | Адреса электронной почты | IP-адреса | Действительные даты | Числовые даты в текст | Номера кредитных карт | Сопоставление полных строк | Удаление повторяющихся строк | Программирование | Два близких слова | | Катастрофический возврат | Слишком много повторений | Отказ в обслуживании | Делаем все необязательным․| Группа повторного захвата | Смешивание Unicode и 8-бит | Как составить электронное письмо с бизнес-запросом с образцами и шаблонами Вы когда-нибудь находили написание бизнес-запроса сложным? Ты не одинок. Это может быть утомительно, но написание вежливых и профессиональных электронных писем с деловыми запросами является важным навыком в современной трудовой жизни. Хорошо написанный деловой запрос, ясный и краткий, поможет эффективно передать ваш запрос. Это должно обеспечить быстрый ответ со всей информацией, необходимой для выполнения вашей работы. Чтобы помочь вам, мы разбили процесс, описав основные части создания эффективного электронного письма для деловых запросов. Мы предоставили набор рекомендаций и рекомендаций, которые помогут любому создать идеальный запрос. Мы также познакомим вас с форматом электронных писем с деловыми запросами, предоставим вам образцы и покажем, как отправлять их с уверенностью и быстрее благодаря нашему шаблону электронных писем с деловыми запросами. К тому времени, как вы прочтете эту статью, вы приобретете знания и навыки, которые дадут вам наилучшие шансы получить нужную вам информацию, когда вы этого хотите, и правильно начинать любые новые отношения. Чтобы быстрее писать качественные бизнес-запросы, попробуйте Flowrite : Что такое бизнес-запрос? Давайте начнем с определения того, что такое бизнес-запрос. Запрос – это запрос информации. Деловой запрос — это официальный запрос информации от организации. Некоторые из причин, по которым вы можете захотеть отправить электронное письмо с деловым запросом, включают:  Запрос каталога, цен или информации о продукте Запрос сведений об услуге Запрос образца продукта Запрос наличия места, например, в гостинице или на выставке. Это всего лишь несколько причин, но существует почти безграничный диапазон ситуаций, когда требуется запросить информацию у другой компании. В некотором смысле бизнес-запрос можно определить как первый шаг в установлении отношений с бизнесом. В конце концов, вы пишете его, чтобы узнать больше об услуге, продукте или компании, которую вы планируете использовать, купить или сотрудничать. Основная характеристика заключается в том, что это сообщение направлено на получение более подробной информации от компании. Итак, вам нужно сделать запрос о бизнесе. Конечно, вы можете просто отправить кому-нибудь сообщение и сказать: «Вы можете отправить мне XXX» или «Я хочу YYY». Однако это может повредить вашей репутации и любой компании, которую вы представляете. Исследователи обнаружили, что при написании онлайн многие из нас склонны писать в диалоговом режиме. В то время как такой подход может быть уместен при письме другу, неформальность может быть воспринята как грубость, невежливость и даже непрофессионализм в деловом общении. Существуют также заметные различия, особенно при общении с предприятиями из разных стран или культур. Например, американцы чаще делают комплименты. Напротив, ученые обнаружили, что корейцы сразу переходят к делу, сравнивая привычки электронной почты двух стран. Придерживаясь установленной структуры, вы избегаете межкультурной путаницы. Основной принцип электронной почты заключается в том, чтобы общаться с «ясностью и сочувствием», — говорит эксперт по коммуникациям и автор Harvard Business Review Эрика Дхаван. Ее совет заключается в том, что вы должны замедлиться и сосредоточиться как на том, что вы говорите, так и на том, как вы это говорите, иначе вы можете повлиять на восприятие вас бизнесом. Полностью согласны. Вот почему мы создали наше полное руководство по этой теме. Остальная часть этого сообщения в блоге поможет вам избежать проблем и распространенных ошибок при создании электронного письма с бизнес-запросом. Как написать электронное письмо с деловым запросом – полное руководство Пришло время начать писать. Каждый бизнес-запрос должен следовать стандартному формату, определяющему его структуру, и набору руководящих принципов, формирующих его содержание. Следующие три части помогут вам сориентироваться в этих нюансах в любой ситуации. Кому адресована ваша электронная почта для деловых запросов? Прежде чем мы возьмемся за бумагу и расскажем, как написать электронное письмо с просьбой предоставить информацию, давайте начнем с определения того, кто ее получит. Ключевой вопрос: вы пишете на личную почту или на корпоративную? Многие организации имеют общий адрес электронной почты для запросов (например, hello@ или info@). При письме на такие адреса электронной почты вы должны быть формальными и прямыми. По сути, вы обращаетесь к организации. Личная электронная почта позволяет вам обращаться к человеку напрямую, обращаясь к нему по имени. Использование чьего-то имени может создать мгновенную связь, но это может быть культурно неприемлемо в мире бизнеса. Советуем быть осторожными. Лучше быть формальным, чем неформальным. Таким образом, вы избегаете риска расстроить или обидеть кого-либо. Нужны еще советы по этикету электронной почты? Тогда наш путеводитель по правилам электронной почты и этикету. Стандартный формат электронной почты для деловых запросов Профессиональный бизнес-запрос следует традиционному формату, в котором четко указывается, что вы хотите. В нем есть пять ключевых аспектов:  Тема электронного письма для запроса Приветствие Текст Закрытие Подписание/подпись Давайте подробно рассмотрим различные части идеального формата электронного письма для деловых запросов. 1. Тема сообщения электронной почты для запроса При написании электронного письма с деловыми запросами старайтесь, чтобы тема сообщения была короткой, приятной и прямолинейной. Лучшая тема электронного письма для запроса — короткая, вежливая и профессиональная. Мы подробно рассмотрим некоторые примеры электронных писем с деловыми запросами позже, но сосредоточимся на том, чтобы в них было как можно меньше слов. 2. Приветствие Здесь важно соблюдать формальности. Если вы не общаетесь с человеком по имени, избегайте «Привет», «Привет» или «Здравствуйте» и придерживайтесь проверенных формальных приветствий, таких как «Дорогой». Использование профессиональных терминов может улучшить восприятие вас и организации, которую вы представляете. Мы описываем, почему это так, и объясняем как начать профессиональную электронную почту в нашей функции. 3. Тело Тело — это основная часть вашего сообщения, в котором вы делаете запрос. Основной принцип при создании электронного письма для деловых запросов — сразу переходить к делу. Причина в том, что мы все тонем под тяжестью цифровой связи, и многие из нас не читают всю электронную почту, — говорит Мэтт Пламмер. Вместо этого мы сканируем его для получения необходимой информации. Чтобы получить ответ, важно, чтобы сообщение было кратким, приятным и прямолинейным. Это также снижает риск непонимания. Предположим, вы запрашиваете несколько частей информации одновременно в своем электронном письме с запросом, например, запрос сведений о ряде продуктов. В этом случае вы можете использовать маркеры, чтобы сделать ваши запросы более четкими, сохраняя при этом небольшое количество слов. 4. Завершение После того, как вы сделали свой запрос, пришлите краткое заключительное заявление по электронной почте с деловым запросом. Здесь полезно наметить, как вы будете использовать информацию, и следующие шаги. Например, если вы просите каталог, вы можете объяснить, что хотите сделать заказ в ближайшее время. В заключении управляйте ожиданиями. Если вам нужна информация к определенной дате, скажите об этом. Кроме того, уточните соответствующие каналы связи. Если вы беспокоитесь о холодных звонках, назовите людям наиболее подходящий канал для связи с вами. 5. Подпись/подпись  Не забудьте добавить соответствующую подпись (с уважением, искренне или аналогичную) и подпись, содержащую все ваши данные, включая имя, должность и контактные данные. Если вы просите кого-то отправить вам что-то по почте, убедитесь, что ваш адрес правильный. Хотите узнать больше о том, как отправить запрос по электронной почте? Прочтите наше руководство о том, как профессионально завершить электронное письмо. Рекомендации по составлению бизнес-запросов  Вдохновленные Harvard Business Review, мы разработали пять рекомендаций по написанию электронных запросов для деловых целей. Следуйте им, и каждый информационный запрос будет передан четко и эффективно. Адаптируйте сообщение Объясните, кто вы Четко объясните, чего вы хотите, когда и почему Будьте кратки и лаконичны Проверьте (затем проверьте еще раз) Давайте рассмотрим эти рекомендации более подробно. 1. Адаптируйте сообщение Люди в бизнесе находятся под давлением, поэтому, чем быстрее вы сможете добраться до сути и конкретнее, тем больше вероятность, что вы получите ответ. Как мы объяснили выше, деловые запросы являются формальным общением, поэтому будьте вежливы и профессиональны, а не пытайтесь быть дружелюбным. Использование стандартного шаблона, взятого с веб-сайта, может неточно передавать или передавать нужное вам сообщение. Усовершенствованные инструменты поддержки письма, такие как Flowrite, помогут вам найти свой подлинный голос. Это дает вам возможность создавать индивидуальные бизнес-запросы, которые являются вежливыми, профессиональными и с большей вероятностью дадут быстрый ответ. 2. Объясните, кто вы Когда вы пишете электронное письмо с деловым запросом или запросите информацию, важно, кто вы. Не бросайтесь сразу в свой запрос. Вместо этого скажите читателю, кто вы. Это дает читателю представление о человеке, с которым он общается, и почему он должен относиться к вам серьезно. 3. Четко объясните, чего вы хотите, когда и почему Отправители электронной почты переоценивают скорость ожидания ответов, как обнаружили исследователи. Электронные письма с деловыми запросами, отправленные в нерабочее время, могут показаться более срочными, создавая необходимость ответить, что может вызвать стресс. Главный вывод: отправляя электронное письмо с деловым запросом, четко указывайте информацию, которую вы запрашиваете, когда она вам нужна и, что особенно важно, для чего. По словам Эйвери Бланк из Forbes, четкое понимание того, что вам нужно и почему, уменьшает путаницу и повышает вероятность того, что вы получите ответ. Преимущество в том, что вы сэкономите время, усилия и потенциальное смущение, связанное с необходимостью отправки дополнительного запроса. Clarity также может защитить вас от получения сотен холодных электронных писем или звонков. Если вы хотите получить ответ по электронной почте, скажите об этом. Если вы ожидаете телефонного звонка, попросите его. Не заставляйте человека сомневаться. 4. Будьте краткими и понятными  Бизнесмены заняты, поэтому пишите кратко. Какой длины должно быть ваше сообщение? Специалисты Hubspot рекомендуют, чтобы ваше электронное письмо содержало от 50 до 125 слов. Хотя может быть невозможно ограничить ваше сообщение 125 словами, в идеале оно должно быть менее 200 слов. 5. Проверьте это (затем проверьте еще раз)  Точность очень важна при написании деловой электронной почты, поэтому обязательно просматривайте и уточняйте свои сообщения перед их отправкой. Если вы отправляете несколько писем одновременно, дважды проверьте важную информацию, например имя получателя и его организацию. Если вы общаетесь на незнакомом вам языке, будьте особенно осторожны. Бесплатные онлайн-проверки орфографии могут плохо понимать контекст или не понимать конкретные технические или профессиональные термины, поэтому не всегда доверяйте их рекомендациям без проверки. Во избежание проблем попробуйте инструмент для письма с искусственным интеллектом, такой как Flowrite, который понимает, к кому вы обращаетесь, и цель вашего сообщения. Когда я должен ответить на запрос о бизнесе? Если вы следовали нашим советам и рекомендациям, приведенным выше, скорее всего, вы получите ответ. Однако, если вы все еще ждете, можно отправить электронное письмо с напоминанием. Мы рассмотрели здесь как создавать электронные письма с напоминаниями , но остается вопрос: когда отправлять электронное письмо с напоминанием о бизнес-запросе? Если ваш запрос не является срочным, дайте человеку хотя бы пару дней, чтобы ответить вам. В экстренных случаях вы можете отправить электронное письмо или даже позвонить раньше. Во всех случаях стоит быть вежливым, когда решаете, как написать последующее электронное письмо. Вероятно, существует реальная причина, по которой кто-то не ответил на ваше сообщение. Примеры электронных писем с деловыми запросами Итак, мы изложили основные принципы создания идеального электронного письма с деловыми запросами. Тем не менее, всегда полезно увидеть их на практике. Чтобы помочь объяснить некоторые основные моменты, мы создали несколько примеров электронных писем с деловыми запросами ниже. Точность и достоверность очень важны при создании запроса по электронной почте. Вы хотите, чтобы люди поняли, что вы настроены серьезно, и вы не добьетесь этого, используя шаблон, в котором вы заполняете пробелы. Вместо того, чтобы копировать и вставлять, используйте их в качестве вдохновения для создания электронной почты. Более того, использование Flowrite — это самый простой и быстрый способ написания электронных писем с деловыми запросами. С помощью последних разработок в области искусственного интеллекта наш инструмент может генерировать аутентичные и персонализированные электронные письма, которые гарантируют, что вы получите необходимую информацию. Электронная почта для организации Если вы отправляете электронное письмо на общий адрес электронной почты, соблюдайте формальность. В этом образце электронного письма с деловым запросом мы просим отправить нам каталог. Это быстро и легко, объясняет, что вы хотите, когда вы хотите и почему. Кому: [email protected] Запрос: Sunset Productions - каталог 2022 Уважаемый господин/госпожа, Меня зовут Сьюзан Деллер, я работаю в Energy Drive. Мы заинтересованы в вашем ассортименте канцелярских товаров и хотели бы узнать больше. Пожалуйста, не могли бы вы отправить мне каталог 2022 года на этот адрес электронной почты? Мы находимся в процессе обновления наших канцелярских принадлежностей и собираемся сделать заказ в ближайшие две недели. В настоящее время мы разговариваем с несколькими поставщиками, и я свяжусь с вами в свое время, если мы захотим разместить заказ. С уважением, Сьюзан Деллер Электронное письмо физическому лицу Формат этого примера электронного письма с деловым запросом по существу такой же, как и первый, но он персонализирован для получателя. Когда вы создаете личную связь, вы увеличиваете шансы на ответ. Опять же, вы увидите, как мы управляем ожиданиями в конце электронного письма вежливо, но твердо. Кому: [email protected] Запрос: Sunset Productions - каталог 2022 Дорогая Сара, Меня зовут Сьюзан Деллер, я работаю в Energy Drive. Мы заинтересованы в вашем ассортименте канцелярских товаров и хотели бы узнать больше. Пожалуйста, не могли бы вы отправить мне каталог 2022 года на этот адрес электронной почты? Мы находимся в процессе обновления наших канцелярских принадлежностей и собираемся сделать заказ в ближайшие две недели. В настоящее время мы разговариваем с несколькими поставщиками, и я свяжусь с вами в свое время, если мы захотим разместить заказ. С уважением, Сьюзан Деллер Запрос подробной информации В этом примере нам нужна дополнительная информация, которая позволит нам принять решение о покупке. Таким образом, вместо длинного, растянутого сообщения маркированные списки поясняют, что нам нужно, когда и почему. Кому: [email protected] Запрос: C4 Председатель Дорогая Сара, Меня зовут Сьюзан Деллер, я работаю в Energy Drive. Мы заинтересованы в вашем ассортименте канцелярских товаров и хотели бы узнать больше о стуле C4. Мои конкретные вопросы заключаются в следующем: Стул доступен в разных цветах или только черный? Нужно ли собирать стул или он поставляется полностью собранным? Если мы закажем более одного стула, сможем ли мы получить оптовую скидку? Мы собираемся сделать заказ на этой неделе, поэтому я был бы признателен за ответ до среды, 12 июня. Если вам нужны какие-либо подробности от меня, пожалуйста, напишите мне здесь, и я отвечу как можно скорее. С уважением, Сьюзан Деллер Написание с помощью шаблона электронного письма с бизнес-запросом Flowrite Flowrite — это инструмент для письма с искусственным интеллектом, который превращает короткие маркеры в полноценные электронные письма и сообщения. Вы просто записываете пару предложений в качестве инструкций, выбираете правильный шаблон и смотрите, как пишется электронное письмо. Когда мы говорим о шаблонах электронной почты, мы не имеем в виду ничего заранее написанного, что вам нужно скопировать и вставить. Вместо этого наши шаблоны помогают ИИ написать правильный тип электронного письма для ваших целей с нуля. Вот пример нашего шаблона бизнес-запроса в действии. Как видите, электронная почта, которую Flowrite генерирует для вас, является персонализированной и контекстно-зависимой. Кроме того, вам не нужно зацикливаться на том, как получатель может воспринять выбор слов или фраз, поскольку вы можете выбрать тон сгенерированного электронного письма. Орфографические и грамматические ошибки? Он также свободно говорит по-английски. Синдром пустого экрана? Выберите шаблон, не указывая никаких пунктов, и Flowrite сгенерирует для вас образец электронного письма. Что я должен вынести из этого? Теперь вы должны понимать, что такое бизнес-запрос (и чем он не является), правильный формат электронной почты с бизнес-запросом и некоторые рекомендации по созданию корпоративной корреспонденции. Добавить комментарий Отменить ответ Ваш адрес email не будет опубликован. Обязательные поля помечены * Комментарий * Имя * Email * Сайт