Сегодня OpenAPI считается стандартом де-факто для описания программных интерфейсов. Основной смысл этих спецификаций в том, что и документация, и серверный интерфейс API генерируются автоматически на основании схемы OpenAPI. Во-первых, это гарантирует актуальность документации и её соответствие реально используемым методам. Во-вторых, сильно облегчает жизнь потребителям API, у которых автоматически генерируется клиентский код.
До появления расширения OpenAPI DevTools проектировать схему OpenAPI приходилось вручную. Хотя это было непросто, оно того стоит в любом случае. Недавно мы в RUVDS переделали свой API под данный стандарт — и увидели, насколько это эффективно и полезно для всех пользователей и разработчиков, которые обращаются к серверным API.
Сейчас в разработке находится четвёртая версия OpenAPI. Она станет проще и универсальнее, то есть подойдёт даже для тех HTTP API, для которых не годится текущая версия 3.0 (3.1.0).
Основную причину для реализации OpenAPI все хорошо знают. Спецификация определяет стандартное, не зависящее от языка программирования описание интерфейса для HTTP API, которое позволяет людям и компьютерам обнаружить и понять возможности сервиса, не требуя доступа к исходному коду, дополнительной документации или изучения сетевого трафика. При правильном определении через OpenAPI потребитель может понять и взаимодействовать с удалённым сервисом с минимальным количеством логики реализации.
Комментарий от наших разработчиков:
Сейчас для добавления или изменения нового метода в API RUVDS первым делом изменяется схема OpenAPI. После этого на основании новой схемы:
- генерируется интерфейс для серверной части API и реализуются методы;
- генерируется документация;
- клиент на основании схемы может генерировать заготовки клиента для множества языков программирования.
Такой подход позволяет поддерживать соответствие документации и реальной реализации с минимальными затратами. Сгенерированные заготовки кода сокращают время разработки клиента для подключения.
Раньше мы работали по старинке: сначала реализовывали методы в серверной части, а потом вручную добавляли их описание в документацию.
Недостатки старого подхода очевидны: документация может не соответствовать реальным методам. При этом клиент читает документацию и реализовывает подключение без возможности получения примеров кода. Сейчас стало на порядок удобнее.
▍ Спецификации OpenAPI
Текущая версия OpenAPI v3.1.0 принята в феврале 2021 года.
Как уже упоминалось, эти спецификации (прежнее название Swagger) стали стандартом де-факто для описания HTTP API. В одном файле описываются все параметры взаимодействия с сервисом. В секции серверов описано, куда идут обращения (начальные пути URL серверов API). В списке путей (paths) — конечные точки, к которым идёт обращение, они содержат в себе запросы и возможные ответы. В секции компонентов (components) — схемы и параметры, совместно используемые в точках доступа, и т. д. Всё довольно логично и понятно.
Спецификации в формате YAML или JSON не привязаны к языку программирования, на котором написан сам API. Эти форматы позволяют легко обмениваться спецификациями и использовать их. Файлы удобны в чтении и использовании как человеком, так и машиной.
Пример шаблона спецификаций в формате JSON:
{
"openapi": "3.1.0",
"info": {
"title": "Non-oAuth Scopes example",
"version": "1.0.0"
},
"paths": {
"/users": {
"get": {
"security": [
{
"bearerAuth": [
"read:users",
"public"
]
}
]
}
}
},
"components": {
"securitySchemes": {
"bearerAuth": {
"type": "http",
"scheme": "bearer",
"bearerFormat": "jwt",
"description": "note: non-oauth scopes are not defined at the securityScheme level"
}
}
}
}С помощью такого файла можно быстро понять, как работает API сервиса и какие у него возможности. Разработчики могут использовать спецификации OpenAPI для настройки своей инфраструктуры, генерации клиентского кода и создания тестовых примеров.
Чем понятнее спецификации API — тем лучше всем. Каждый сервис заинтересован в том, чтобы его программные интерфейсы использовались как можно активнее. С другой стороны, каждый потребитель желает более понятных и ясных спецификаций, с которыми удобнее работать.
Благодаря OpenAPI потребителю не требуется разбираться в архитектуре сервиса, устройстве приложения или пытаться выучить Lisp или Haskell, если наши API написаны на этом языке. Достаточно взглянуть на файл JSON, написанный на простом и выразительном языке.
Спецификация обеспечивает именно такую передачу знаний от поставщика API к потребителю API. Это открытый стандарт, который содержит полный словарь терминов, отражающий общепринятые понятия в мире API, и включает в себя основы HTTP и JSON.
Предоставление и использование документа OpenAPI — очень важное действие, которое является основополагающим для всего жизненного цикла API, начиная от разработки и заканчивая развёртыванием и поддержкой. Если жизненный цикл API рассматривать как транспортную сеть, то OpenAPI — это главная артерия, которая предоставляет средства для эффективной передачи больших объёмов нужной информации быстро и эффективно. Эти спецификации можно использовать на каждом этапе этого жизненного цикла API:
К настоящему моменту разработано большое количество инструментов с поддержкой OpenAPI. Но есть и проблемы. Из-за исторически сложившегося мнения, как должны работать HTTP API, третья версия не поддерживает некоторые специфичные варианты интерфейсов.
С одной стороны, разработчики просят увеличить количество описаний для поддержки большего числа сценариев. В то же время другие сетуют на то, что OpenAPI стал слишком сложным для ручной разработки. В общем, четвёртая версия должна решить все эти проблемы.
▍ Изменения в OpenAPI v4
Предложение OpenAPI v4 (aka Moonwalk) пока находится в стадии обсуждения и может сильно измениться ближе к финальной версии. Однако первые отзывы на него положительные, поэтому разработчики уверены, что двигаются в правильном направлении.
Идея изменений в новой версии — упростить схему OpenAPI и в то же время сделать её более гибкой. Это попытка лучше учитывать существующие стандарты и свести к минимуму добавление новой функциональности. Суть изменённой модели показана на диаграмме:
Главное новшество OpenAPI v4 — упрощение схемы. Это основная проблема, на которую жалуются нынешние пользователи OpenAPI v3. Как видно на диаграмме вверху, упрощённая схема основана на трёх основных структурных компонентах: pathItem, request и response.
Кроме упрощения конструкции, при разработке четвёртой версии принимались в расчёт следующие задачи:
- Поддержка API, которые отдают разные ответы в зависимости от параметров запроса, заголовков и тела запроса.
- Поддержка более широкого спектра шаблонов проектирования URL.
- Сокращение вложенных структур для улучшения читабельности и редактируемости.
- Улучшение возможности повторного использования шаблонов запросов и ответов.
Из официального анонса:
Сейчас у элемента
pathItemесть свой набор операций, по одной для каждого поддерживаемого HTTP-метода. В такой конструкции имеется неявное предположение, что HTTP-метод в пути может описывать только одно взаимодействие с одним и тем же набором ответов.В OpenAPI v4, напротив, реализованы минимальные ограничения на то, сколько различных типов запросов может быть выполнено на одном пути. Практически любую часть запроса можно использовать для сигнализации об уникальном наборе ответов.
Если в OpenAPI v3 ключ для объекта
pathItemбыл ограничен только частью пути в URL, то в четвёртой версии ключами pathItem могут быть полные шаблоны URI. Это позволит использовать параметры запроса для идентификации ресурса и соответствующих запросов, а также устранит необходимость в определении параметров, содержащих информацию о сериализации, поскольку шаблон URI может полностью описать, как сериализовать параметры шаблона. Использование интернет-стандарта сократит объём работы для поддержки построения URL со стороны инструментария. Это может решить давнюю проблему однозначного соотнесения URL с соответствующимpathItem.
Как видим, изменения значительные.
Пример простого описания в OpenAPI 4.0:
openapi: 4.0.0
info:
title: Simplest thing that works
version: 0.5.0
paths:
"speakers":
requests:
createSpeaker:
method: post
contentType: application/json
contentSchema:
$ref: "#/components/schemas/speaker"
responses:
created:
status: 201
getSpeakers:
method: get
responses:
ok:
status: 200
contentType: application/json
contentSchema:
type: array
items:
$ref: "#/components/schemas/speaker"
pathResponses:
notFound:
status: 404
contentType: application/http-problem
apiResponses:
serverError:
status: 5XX
contentType: application/http-problem
components:
schemas:
Speaker:
type: object
properties:
name:
type: stringТо же самое в OpenAPI 3.1.0:
openapi: 3.1.0
info:
title: Simplest thing that works
version: 0.5.0
paths:
"/speakers":
post:
requestBody:
content:
application/json:
schema:
$ref: "#/components/schemas/speaker"
responses:
201:
description: created
404:
description: notFound
content:
application/http-problem: {}
5XX:
description: serverError
content:
application/http-problem: {}
get:
responses:
200:
description: retrieved
content:
application/json:
schema:
type: array
items:
$ref: "#/components/schemas/speaker"
404:
description: notFound
content:
application/http-problem: {}
5XX:
description: serverError
content:
application/http-problem: {}
components:
schemas:
Speaker:
type: object
properties:
name:
type: stringВ варианте OpenAPI 4.0 на 20% меньше строк и на один уровень вложенности меньше. То есть описание реально стало проще.
Осталось подождать утверждения и принятия четвёртой версии. Мы видим, насколько эффективно и удобно использование стандартных интерфейсов OpenAPI. Благодаря внедрению открытого стандарта пользователь может быстро понять, как работает API, настроить инфраструктуру и сгенерировать клиентский код. Реализация OpenAPI у нас оказалась очень удачным решением. Остаётся пожелать, чтобы все остальные инфраструктурные сервисы тоже внедрили открытый стандарт для всеобщей пользы.
Автор:
ru_vds
