OpenAPI особенно подходит для описания и разработкиREST API. Написанный в YAML или JSON, OpenAPI предоставляет стратегию записи конечных точек, задач, обязательных/необязательных параметров, тестов кода и практически всего, что вы хотите сообщить о своем программировании API interface. Эти архивы эффективно очищаются людьми и машинами, быстро изменяются и, что удивительно, создаются прямо из кодовой базы.
Ранее известная как Swagger, а затем переименованная в спецификацию OpenAPI (OAS) в 2016 году, OAS сразу же стала преобладающей структурой для отображения REST API. К середине 2017 года число загрузок инструментов OAS превысило 100 000 в день, и они продолжают развиваться.
Спецификация в настоящее время находится в третьей итерации и представляет собой значительную основную поставку с момента ее перехода к инициативе OpenAPI. Так что же такого особенного в недавнем релизе, если он оказался таким успешным и эффективным?
Давайте подробно обсудим различные новые функции OpenAPI 3.0.
Используется в случае промежуточных и рабочих серверов
Предыдущая версия 2.0 позволяла вам установить хост, базовый URL-адрес и планы для применения в документации по интерфейсу Programming API. В OAS 3.0 эти поля объединяются в свойство сервера, собирая отчет и предлагая справку по различным базовым URL-адресам.
Их можно охарактеризовать позже в архиве, чтобы при необходимости отдельные конечные точки могли иметь свои уникальные базовые URL-адреса. Его можно использовать на промежуточных и производственных серверах.
Несмотря на то, насколько жизнеспособным может быть устройство, оно мало чего стоит, потому что его трудно изучить, переварить, настроить и запустить. Учитывая это, OAS 3.0 выделяет несколько изменений после сбора и улучшает структуру для удобства чтения и удобства.
Мы должны посмотреть отчет YAML для OAS 2.0 и 3.0, чтобы показать часть этих сравнений. OAS 3.0 включает в себя несколько корректировок текущего объекта частей для достижения этой цели, уделяя особое внимание возможности повторного использования и согласованности всей записи.
Схема OpenAPI теперь является допустимой схемой JSON.
Объект Schema характеризует все, что находится внутри ключевого слова schema в OpenAPI. Он всегда был неточно основан на Схеме JSON и упоминался как надмножество подмножества, потому что он добавляет несколько вещей и исключает одну вещь из схемы JSON.
Это сбило с толку нескольких человек в группе людей OpenAPI. Создатели двух сетей скорректировали эти детали, чтобы определить проблему надмножества подмножества.
OpenAPI v3.0 зависел от черновика схемы JSON 05, и с этого момента схема JSON претерпела несколько черновиков, т. е. Draft 06, черновик 07 и черновик 2019–09. Что касается вклада клиентов и специалистов по сопровождению инструментов во время выпуска кандидатов версии 3.1.0, был представлен еще один небольшой проект: Черновик 2020–12.
Он должен быть последним оставшимся на какое-то время. Группа JSON Schema не разрабатывает существенных изменений, поэтому, если все сработает положительно, последний выпуск близок к тому, чтобы избежать других несоответствий.
Структурные изменения
Итак, теперь базовая структура файла OAS3.0 будет выглядеть так, как показано ниже.
openapi: 3.0.0
info:
version: '1.0.0'
title: 'My Service APIs'
description: 'API to demonstrate OAS3.0.'
paths: {}
Поменять местами допустимые значения null для массивов типов
Благодаря схеме JSON ключевое слово «тип» теперь может характеризовать различные типы шаблонов с массивом. Это полезная новая функция, но она также сделала повторяющиеся обнуляемыми значениями. Чтобы достичь цели, позволяющей устройствам схемы JSON понимать OpenAPI, было решено исключить обнуляемое значение, а не цензурировать его.
# OpenAPI v3.0 type: string nullable: true # OpenAPI v3.1 type: - "string" - "null"
Это соответствует идее независимости ключевого слова, где ключевое слово должно добавлять ограничения; однако добавление другого ключевого слова не должно отменять императив. Найдите и уладьте это довольно быстро.
Настройка эксклюзивного минимума и эксклюзивного максимума
Эти два ключевых слова принимают логическое значение, которое изменяет значение свойств `минимум` и `максимум`. В OpenAPI v3.1 они обозначаются отдельными значениями.
# OpenAPI v3.0 minimum: 7 exclusiveMinimum: true # OpenAPI v3.1 exclusiveMinimum: 7
Используйте примеры, а не примеры.
В OpenAPI есть много мест, где можно найти пример или несколько примеров. OpenAPI версии 3.0 может иметь «пример» или «примеры» на уровне типа носителя (запросы, реакции, обратные вызовы и веб-перехватчики). Он также может иметь другой тип «примера» внутри объекта схемы. Конкретным примером этого объекта сопоставления было ключевое слово OpenAPI-explicit, которое в настоящее время является чрезмерным, поскольку в шаблоне JSON есть «примеры».
По сути, изменение любого примера внутри схемы на примеры и добавление тире в начале (это массив YAML). Это серьезно, если вы пишете YAML полностью вручную, а не используете визуальный супервайзер. Тем не менее, в то же время это компонент: в настоящее время гораздо проще добавлять различные примеры.
Раньше, чтобы получить множество примеров для свойства или схемы, вам нужно было переключить используемую модель с руководства по свойствам на примеры медиа-типа, что казалось чрезмерным излишеством.
Компоненты многократного использования
Все параметры, ответы и определения представлены в неэксклюзивном компонентном объекте. Объект определений в настоящее время переименован в схемы. Обратите внимание, что аналогичный объект схемы также может использоваться в тексте запроса и ответа.
openapi: 3.0.0
info:
version: '1.0.0'
title: 'My Service APIs'
description: 'API to demonstrate OAS3.0'
paths: {}
components:
Schemas:
Employee:
properties: {}
Схема $теперь разрешена
Ключевое слово $schema является произвольным; однако полезно точно определить, на каком именно диалекте схемы JSON написана модель, что может быть различными черновиками или даже пользовательскими языками. Устройства, которые поддерживают разные диалекты, могут обрабатывать записи несколько неожиданно, а это означает, что вам не обязательно менять каждую из ваших моделей при последующей перестройке вариантов OpenAPI.
OpenAPI, без сомнения, жизнеспособен со схемой JSON, поскольку в настоящее время это диалект схемы JSON, поэтому, само собой разумеется, любое сопоставление использует схему $ https://spec.openapis.org/oas/3.1/dialect/base диалекты. Если вы разделите свои шаблоны на другие документы JSON/YAML и используете $ref для их выделения, они могут содержать альтернативную схему $ и заменить это значение по умолчанию.
{
$schema: "https://json-schema.org/draft-07/schema#",
}
Полезные данные для загрузки файлов
В OpenAPI v3.0 передача документов обозначалась типом: строка, а конфигурация была установлена на byte, parallel или base64. JSON Schema объясняет это ключевыми словами contentEncoding и contentMediaType, которые предназначены именно для этой цели.
Улучшенная возможность повторного использования
Общий дизайн OAS 3.0 улучшен для повторного использования. Хост, базовый путь и схемы перемещены в другую идею, называемую серверами. Производит, потребляет, а пути в настоящее время называются путями. Любые оставшиеся части, подобные определениям, параметрам и реакциям, впредь условно называются компонентами.
Определение сервера
Теперь вы можете охарактеризовать серверы для своих API. Предположим, у вас есть три работающих сервера: организационный, бета-версия и работающий. Вы можете охарактеризовать их в своих API, и ваши конечные точки могут быть зарегистрированы для каждого сервера.
openapi: 3.0.0 info: version: '1.0.0' title: 'My Service APIs' description: 'API to demonstrate OAS3.0'
Новые параметры заголовков
Помочь вам определить параметр, который ваш API использует на основе заголовков HTTP-запроса. Помочь вам определить границу, которую использует интерфейс Programming API из-за заголовков HTTP-запроса.
name: limit
in: header
schema:
type: integer
minimum: 10
maximum: 100
example: 20
Новые параметры файлов cookie
В API на основе сеанса файлы cookie являются одним из важных компонентов. Следовательно, с OAS3.0 теперь вы можете определять параметры в зависимости от файлов cookie.
Paths:
/employees:
get:
parameters:
- name: limit
in: cookie
schema:
type: integer
minimum: 10
maximum: 100
example: 20
Новый параметр requestBody
При отправке запроса POST границы тела не нужны. Его заменяет тело запроса. При прочих равных можно охарактеризовать полное тело запроса как предварительное, которое мы представляем для реакции, в любом случае, для разных типов контента. Тело запроса дополнительно позволяет отправлять информацию о структуре.
paths:
/employees:
post:
requestBody:
required: true
content:
application/JSON:
schema: {}
application/XML:
schema: {}
Использование объекта схемы для параметра
В настоящее время характеристика любого параметра требует значительного использования объектов схемы в каждом мыслимом варианте использования.
paths:
/employees:
get:
parameters:
- name: limit
in: query
schema:
type: integer
minimum: 10
maximum: 100
example: 20
Контент важен для API и претерпел несколько существенных изменений.
- Потребление и производство исключены
Теперь его можно охарактеризовать индивидуально, в зависимости от типов медиа тела запроса и ответа.
- Различные типы мультимедиа
Его можно охарактеризовать исключительно в телах запроса и ответа. Расширение возможностей вашего интерфейса Programming API для поддержки одного типа ответа для одной конечной точки и другого типа ответа для другой конечной точки.
Диапазоны ответов
Вместо того, чтобы характеризовать отдельные ответы, теперь вы можете характеризовать коды диапазонов. Вы можете охарактеризовать один ответ для всех диапазонов 200 и еще одну реакцию для всех диапазонов 400. Поддерживаемые диапазоны: 1XX, 2XX, 3XX и 4XX.
Поддержка описания обратных вызовов
Это новый элемент OAS3.0. Если вы хотите охарактеризовать конечную точку интерфейса Programming API, которая будет вызывать URL-адрес при завершении запроса, это можно описать сейчас.
С каждым из новых возможностей и адаптивности OpenAPI 3.0 разработчики документации могут влиять на план, разработку и, наконец, на прогресс своих API. В ближайшие годы мы увидим новейшие функции OpenAPI 3.0. Следите за нами и узнавайте обо всех изменениях, происходящих в Open API 3.0.
Пожалуйста, прокомментируйте ниже или свяжитесь с нами для любых запросов, вопросов или предложений. Спасибо!
Создавайте API с повторно используемыми компонентами — прямо как Lego!
Инструмент с открытым исходным кодом Bit помогает более чем 250 000 разработчиков создавать приложения с компонентами.
Превратите любой пользовательский интерфейс, функцию или страницу в компонент многократного использования — и поделитесь им со своими приложениями. Легче сотрудничать и строить быстрее.
Разделите приложения на компоненты, чтобы упростить разработку приложений, и наслаждайтесь наилучшими возможностями для рабочих процессов, которые вы хотите:
