OpenAPI: что это такое и как с ним работать

Запрос «open api» означает две разные вещи. Чаще всего — OpenAPI Specification: открытый стандарт машиночитаемого описания HTTP API, из которого автоматически получают документацию, клиентские SDK и тесты. Реже — «открытый API», то есть публичный интерфейс сервиса для сторонних разработчиков. Эта статья — о спецификации: какая версия актуальна, из чего состоит документ, как написать первый файл и чем его проверить.

Коротко по сути:

• OpenAPI — формат описания REST API в YAML или JSON; сам по себе он ничего не выполняет, а служит контрактом между бэкендом, фронтендом и тестами.
• Актуальная версия спецификации — 3.2.0 от 19 сентября 2025 года по самому документу спецификации; на FAQ сайта OpenAPI Initiative при этом до сих пор значится 3.1.1 от 24 октября 2024 (разбираем расхождение ниже). В проектах по-прежнему массово живут 3.1.x и 3.0.x.
• Спецификация выросла из Swagger: SmartBear передала Swagger 2.0 в 2015 году, в 2016-м проект стал отдельным под управлением OpenAPI Initiative — коллаборации Linux Foundation.
• Минимальный валидный документ — это три обязательных элемента: строка версии openapi, блок info и хотя бы один из разделов paths, components, webhooks.
• Схемы данных в 3.1 и 3.2 совместимы с JSON Schema 2020-12, поэтому один и тот же файл описывает и REST-эндпоинты, и инструменты для ИИ-агентов.

Open API и OpenAPI: в чём разница

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

OpenAPI (одним словом) — название стандарта. Это формализованное описание HTTP API: эндпоинты, методы, параметры, тела запросов, коды ответов, схемы данных и способы аутентификации в одном машиночитаемом файле. Стандарт ведёт OpenAPI Initiative, проект Linux Foundation, основанный в ноябре 2015 года SmartBear, 3Scale, Apigee, Capital One, Google, IBM, Intuit, Microsoft, PayPal и Restlet.

Открытый API (open API, два слова) — не стандарт, а свойство продукта: интерфейс, который компания публикует наружу для сторонних разработчиков. В русскоязычной выдаче по этому смыслу отвечают финтех-источники: Банк России описывает Открытые API как интерфейсы, которые «позволят компаниям более оперативно обмениваться информацией о клиенте при его согласии, предоставлять ему выгодные персонализированные услуги». Открытый API может быть описан спецификацией OpenAPI, а может не быть описан вовсе — это независимые вещи.

Практический критерий: если вам нужен файл, который читают Swagger UI, генератор кода или валидатор — это OpenAPI. Если нужен доступ к чужому сервису по токену — это открытый API конкретной платформы, и разбираться надо в её документации. Например, у российских нейросетей публичные интерфейсы устроены по-разному: см. разбор Гигачата от Сбера.

Дальше в статье речь только о спецификации.

Какая версия OpenAPI актуальна

Версии нумеруются по схеме major.minor.patch, и патч-версии внутри одной минорной инструменты считают взаимозаменяемыми. Актуальный документ спецификации на spec.openapis.org помечен как «Version 3.2.0, 19 September 2025».

Здесь источник противоречит сам себе, и об этом стоит знать до того, как вы начнёте спорить с коллегой. Страница FAQ на сайте OpenAPI Initiative на дату проверки (30 июля 2026 года) утверждает другое: «The latest OpenAPI Specification version is 3.1.1 published October 24, 2024». То есть один и тот же проект в одном месте называет свежей 3.2.0, а в другом — 3.1.1. Мы берём версию из самого документа спецификации: он нормативный и опубликован позже, а FAQ — справочная страница, которую после релиза не обновили. Если вам нужен формальный аргумент в ревью — ссылайтесь на шапку документа, а не на FAQ.

Что именно добавили в 3.2.0, по анонсу OpenAPI Initiative: новая структура Tag Object с полями summary, parent и kind — теги наконец складываются в дерево, а не в плоский список; встроенная поддержка метода query «для безопасного идемпотентного запроса состояния ресурса с телом запроса»; additionalOperations для методов, которых нет в списке первого класса; потоковые медиатипы text/event-stream, application/jsonl, application/json-seq и multipart/mixed; в безопасности — OAuth 2.0 Device Authorization Flow и свойство oauth2MetadataUrl.

Вывод для практики: писать новый файл на 3.1.x безопаснее всего, а 3.2.0 брать под конкретную потребность — стриминг событий или API, который не укладывается в GET/POST/PUT/DELETE.

OpenAPI: основные понятия

Спецификация описывает REST API набором вложенных объектов. Ниже — те, без которых не обходится ни один файл.

Документ (OpenAPI Document)

Документ — это, по формулировке самой спецификации, «JSON-объект, который может быть представлен в формате JSON или YAML». На практике пишут в YAML: меньше скобок и допустимы комментарии. Обязательных полей в корне три: openapi, info и хотя бы один из paths, components, webhooks. Всё остальное — опционально.

Версия АПИ и версия спецификации

Это два разных числа, и их постоянно путают. Поле openapi в корне — версия стандарта, по которому написан файл (например, 3.1.0). Поле version внутри info — версия вашего API (например, 1.4.0). Валидатор ругается на первое, клиенты ориентируются на второе.

Информация (Info Object)

Раздел info содержит метаданные: название, описание, версию API, контакты владельца и лицензию. Его читают генераторы документации и выводят в шапку.

Серверы (Servers)

Раздел servers задаёт базовые URL, к которым дописываются пути из paths. Несколько окружений перечисляются списком — Swagger UI покажет их выпадающим списком и подставит выбранный в тестовые запросы.

Эндпоинты (Paths)

Раздел paths перечисляет маршруты относительно базового URL. Внутри маршрута — HTTP-методы, внутри метода — параметры, тело запроса и ответы.

Методы (Operations)

Каждый маршрут поддерживает один или несколько методов:

• GET — получение данных
• POST — создание ресурса
• PUT и PATCH — полное и частичное обновление
• DELETE — удаление

С версии 3.2.0 к ним добавился query, а остальные методы описываются через additionalOperations. У операции есть служебное поле operationId — уникальный идентификатор, из которого генераторы делают имена функций в SDK. Без него сгенерированный клиент получит имена вида getUsersGet.

Параметры (Parameters)

• Query-параметры — в строке запроса, например ?limit=20
• Path-параметры — внутри пути, например /users/{id}; для них required: true обязателен
• Header-параметры — в HTTP-заголовках
• Cookie-параметры — в куках

Тело запроса параметром не считается: у него отдельный объект requestBody с медиатипом и схемой.

Схемы данных (Schemas) и компоненты (Components)

Раздел components — библиотека переиспользуемых кусков: схем данных, параметров, заголовков, ответов и схем безопасности. На них ссылаются через $ref, и описание объекта живёт в одном месте, а не копируется в каждый эндпоинт. В версиях 3.1 и 3.2 схемы строятся по JSON Schema 2020-12, поэтому тот же файл понимают валидаторы, не имеющие отношения к HTTP.

Ответы (Responses)

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

Описывать только «двухсотые» — самая частая недоработка: клиент, сгенерированный из такого файла, не знает, что делать с ошибкой.

Аутентификация и авторизация (Security)

Способы доступа объявляются в components.securitySchemes, а затем применяются либо ко всему API, либо к отдельной операции:

• API-ключ — в заголовке, куке или строке запроса
• HTTP-схемы — Basic и Bearer, в том числе JWT
• OAuth 2.0 — с версии 3.2.0 доступен и Device Authorization Flow
• OpenID Connect — через openIdConnectUrl

Минимальный документ OpenAPI целиком

Разрозненные куски выше складываются в один файл. Вот полный валидный документ — его можно скопировать в редактор и увидеть готовую страницу документации.

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

Как создать спецификацию: пять шагов

Порядок ниже — схема работы «design-first»: контракт пишется до кода, и обе команды идут от него параллельно.

1. Метаинформация. Заведите файл openapi.yaml, укажите версию стандарта и блок info с названием и версией API.
2. Маршруты. Опишите пути и методы — сначала сигнатуры без деталей, чтобы увидеть карту API целиком.
3. Модели данных. Вынесите объекты в components.schemas и ссылайтесь на них через $ref. Дубли схем — источник расхождений между документацией и кодом.
4. Примеры и ошибки. Добавьте example к полям и опишите коды ошибок, а не только успешный ответ.
5. Валидация. Прогоните файл линтером и подключите проверку в CI, чтобы невалидная спецификация не доезжала до ветки по умолчанию.

Где писать. Откройте Swagger Editor — по описанию SmartBear, он позволяет «проектировать API в редакторе, который визуально отрисовывает определение OpenAPI или AsyncAPI и даёт обратную связь по ошибкам в реальном времени». Правая половина экрана показывает результат, левая — YAML; ошибка подсвечивается на строке, где вы её сделали. Для командной работы файл кладут в репозиторий рядом с кодом и ревьюят пул-реквестами: спецификация — такой же исходник, как модуль на бэкенде.

Разбиение на файлы. Когда документ переваливает за несколько сотен строк, схемы выносят в отдельные YAML и подключают через $ref: './schemas/user.yaml'. Сборщик склеит их в один файл перед публикацией.

Мини-вывод: спецификация полезна ровно настолько, насколько она проверяется автоматически. Файл, который никто не валидирует, расходится с реальным API за пару спринтов.

Инструменты для работы с OpenAPI

Ценность спецификации создаёт не файл, а тулинг вокруг него. Базовый набор:

Отдельная категория — облачные шлюзы. В глоссарии Yandex Cloud OpenAPI определён как «открытый стандарт или спецификация для машиночитаемого описания HTTP API, таких как REST-API». А в документации Yandex Cloud API Gateway расширения сервиса описываются прямо внутри спецификации: про их поля там сказано «Описание остальных параметров читайте в спецификации OpenAPI 3.0». Вывод отсюда практический: у такого шлюза спецификация служит не только описанием, но и местом, где живёт конфигурация.

Тестировщикам спецификация даёт готовый источник кейсов: коллекция запросов импортируется в Postman из файла, а контрактные тесты сверяют реальные ответы сервиса со схемами. Мини-вывод: если в проекте есть OpenAPI, но нет ни генерации, ни валидации по нему, вы платите за документацию и не получаете сдачи.

Зачем OpenAPI нужен при работе с ИИ-агентами

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

Чтобы языковая модель могла вызвать внешний сервис, ей нужно машиночитаемое описание этого сервиса. В документации OpenAI для Actions сказано прямо: «A GPT Action requires an Open API schema to describe the parameters of the API call, which is a standard for describing APIs» — то есть подключение стороннего API к GPT сводится к тому, чтобы дать ему валидный OpenAPI-файл; в примере из документации используется openapi: 3.1.0. Модель читает summary, description и схемы полей и по ним решает, какой эндпоинт дёрнуть и что подставить в параметры.

Отсюда практическое следствие, которого нет в обычных руководствах: описания в спецификации перестали быть косметикой. Раньше пустой summary означал неудобную документацию для человека, теперь он означает, что агент выберет не тот метод. Поля operationId, description и example работают как промпт для модели — и писать их надо так же придирчиво.

Совместимость схем 3.1 с JSON Schema 2020-12 сделала это возможным без переходников: тот же формат используется в описаниях инструментов для function calling. Один файл описывает API и для человека, и для SDK, и для агента.

Что это меняет в работе: чтобы дать нейросети доступ к внутреннему сервису, не нужен отдельный плагин — достаточно поддерживать спецификацию в актуальном состоянии. Про то, как ИИ-инструменты работают с кодом и внешними интерфейсами, есть отдельные разборы: что такое Claude Code и чем он отличается от Cursor.

Преимущества OpenAPI

• Документация не пишется руками. Swagger UI и Redoc собирают интерактивную страницу из файла, а значит, она не расходится с контрактом.
• Код генерируется. Swagger Codegen и OpenAPI Generator делают клиентские SDK и серверные заглушки для Python, Java, JavaScript и десятков других языков.
• Тесты опираются на схему. Postman, Prism и контрактные тесты берут ожидания из спецификации, а не из головы тестировщика.
• Разработка идёт параллельно. Фронтенд работает по мок-серверу, пока бэкенд ещё пишется.
• Общий язык у команды. Аналитик, разработчик, тестировщик и техписатель обсуждают один файл вместо четырёх пониманий.
• Версионирование прозрачно. Изменения контракта видны в диффе пул-реквеста построчно.
• Микросервисы и шлюзы. Один файл описывает контракт между сервисами, а у облачных шлюзов в нём же живёт конфигурация — пример с Yandex Cloud API Gateway разобран выше.

Частые ошибки в спецификации

• Путают версию стандарта и версию API. Поле openapi — про спецификацию, info.version — про ваш сервис.
• Описывают только успешные ответы. Сгенерированный клиент в итоге не умеет обрабатывать ошибки.
• Копируют схемы вместо $ref. Через полгода копии расходятся, и документация начинает врать.
• Забывают operationId. Имена методов в SDK получаются нечитаемыми.
• Пишут required наугад. Валидатор пропускает запрос, а сервис падает на пустом поле.
• Держат файл вне репозитория. Спецификация в вики устаревает в тот же день, когда в код уезжает новый эндпоинт.
• Не валидируют в CI. Ошибку находит не линтер, а клиент интеграции.

Заключение

OpenAPI — это способ описать HTTP API один раз и получить из описания документацию, клиентов, моки и тесты. Начать стоит с минимального файла на 3.1.x, положить его в репозиторий, подключить валидацию в CI и только потом наращивать детали. Тогда спецификация остаётся источником правды, а не отдельным документом, который никто не открывает.

Частые вопросы

Open API и OpenAPI — это одно и то же?

Нет. OpenAPI — стандарт описания HTTP API. Открытый API (open API) — публичный интерфейс конкретного сервиса, который может быть описан этим стандартом, а может не быть описан вовсе.

Чем OpenAPI отличается от Swagger?

Swagger — исходное название спецификации и семейство инструментов SmartBear. Компания передала Swagger 2.0 в 2015 году, в 2016-м спецификация стала отдельным проектом OpenAPI Initiative под управлением Linux Foundation. Стандарт теперь называется OpenAPI, а Swagger UI, Editor и Codegen — инструменты для работы с ним.

Какая версия OpenAPI актуальна в 2026 году?

Ответ зависит от того, куда смотреть, и это не шутка. Сам документ спецификации помечен как версия 3.2.0 от 19 сентября 2025 года, а FAQ на сайте OpenAPI Initiative на 30 июля 2026 года всё ещё называет актуальной 3.1.1 от 24 октября 2024 года. Опираться стоит на документ спецификации: он нормативный и вышел позже. Для нового проекта безопасный выбор — 3.1.x: её поддерживает практически весь тулинг.

YAML или JSON?

Спецификация допускает оба формата: документ — это JSON-объект, представленный в JSON или YAML. Люди пишут в YAML из-за комментариев и меньшего количества скобок, машины одинаково читают оба.

Нужно ли уметь программировать, чтобы написать спецификацию?

Нет. Файл описывает контракт, а не логику: достаточно понимать HTTP-методы, структуру URL и типы данных. Реализацию потом пишет разработчик или генератор.