Wiki · Технологии разработки

OpenAPI (Swagger)

4 мин чтенияАвтор: Сергей ЧерняковСоавторы: Евгений Баев

OpenAPI (раньше называлась Swagger) – это открытый стандарт, по которому API описывают в одном файле формата YAML или JSON: какие есть адреса, что им передать и что они вернут. По этому файлу строят документацию, генерируют код и проверяют запросы.

Если у вашего сайта или личного кабинета есть API, через который он обменивается данными с мобильным приложением, 1С или CRM, у этого API должно быть описание. Иначе знание о нём живёт в голове одного программиста. OpenAPI – самый распространённый способ такое описание оформить.

Swagger и OpenAPI: одно и то же или нет

Формат появился под названием Swagger Specification. В 2015 году компания SmartBear передала его в открытый проект OpenAPI Initiative при Linux Foundation, и спецификацию переименовали в OpenAPI. Название Swagger осталось за набором инструментов SmartBear, которые с ней работают:

Swagger UI: страница с интерактивной документацией, где каждый запрос можно отправить кнопкой;
Swagger Editor: редактор спецификации в браузере с подсветкой ошибок;
Swagger Codegen: генерация заготовок сервера и клиентских библиотек по файлу.

В разговоре «дайте сваггер» обычно значит «дайте описание API». На октябрь 2026 года последняя версия спецификации OpenAPI 3.2.1, опубликована 10 сентября 2026 года. На практике у многих проектов ещё версии 3.0 или 3.1, а у старых встречается Swagger 2.0.

Что записано в файле спецификации

Условный пример: фрагмент описания запроса, который отдаёт заказ по номеру.

paths:
  /orders/{id}:
    get:
      summary: Получить заказ по номеру
      responses:
        '200': {description: Заказ найден}
        '404': {description: Заказа нет}

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

Схема: из одного файла спецификации OpenAPI получают документацию Swagger UI, сгенерированный код клиента и сервера и автоматическую проверку ответов — Что получают из одного файла OpenAPI

Многие фреймворки собирают спецификацию из кода сами. Например, FastAPI отдаёт готовую страницу документации без дополнительной работы, для Laravel, Django и Spring есть пакеты, которые делают то же.

Зачем требовать описание API от подрядчика

Приложение и сайт можно делать параллельно. Команды договорились о файле, и каждая работает со своей стороны, не дожидаясь другой.
Новая интеграция стоит дешевле. Разработчик 1С или CRM читает спецификацию, а не переписывается неделю с автором API.
Проверка становится формальной. Ответ сервера сравнивают с описанием автоматически, расхождения видны сразу.
Проект проще передать другой команде. Описание API вместе с кодом и доступами входит в то, что вы забираете у подрядчика.

Пункт про спецификацию стоит вписать в техническое задание заранее: в каком формате, где лежит, кто обновляет при изменениях. Описание, которое составили один раз и забыли, через полгода врёт хуже, чем его отсутствие.

Как проверить, что описание API настоящее

Откройте Swagger UI или загрузите файл в Swagger Editor и пройдитесь по нескольким пунктам:

есть ли у каждого запроса описание по-русски или хотя бы понятное название;
описаны ли ответы с ошибками: 400, 401, 404, а не один успешный 200;
совпадает ли описание с реальностью: отправьте пару запросов прямо со страницы или через Postman, куда спецификация импортируется в коллекцию;
видна ли страница документации всему интернету. Для внутреннего API её закрывают паролем или открывают только в тестовом окружении.

Чек-лист приёмки спецификации OpenAPI: описания запросов, ответы с ошибками, проверка запросов, файл в репозитории, закрытая документация — Как проверить описание API от подрядчика

Последний пункт касается безопасности: открытый Swagger UI на боевом сервере показывает посторонним полный список запросов. Сам по себе это не взлом, но облегчает работу тому, кто ищет уязвимость.

Описание API в OpenAPI, Swagger UI и передача проекта

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

OpenAPI – это сама спецификация, то есть правила, по которым описывают API в файле. Swagger сейчас название инструментов SmartBear для работы с ней: Swagger UI, Swagger Editor, Swagger Codegen. До 2015 года спецификация тоже называлась Swagger, отсюда путаница.

Как открыть файл swagger.json или openapi.yaml?

Файл спецификации проще всего открыть в Swagger Editor: вставьте содержимое, и справа появится документация. Ещё его можно импортировать в Postman или Insomnia, тогда запросы сразу соберутся в коллекцию для проверки.

Как OpenAPI связан с REST API?

OpenAPI создан для описания REST API, то есть API, которые работают через обычные HTTP-запросы к адресам вроде /orders/15. Для других подходов есть свои форматы: у gRPC описание хранится в proto-файлах, у GraphQL в схеме, а для событийных систем и очередей сообщений есть отдельный стандарт AsyncAPI. Поэтому, если подрядчик говорит, что API «не REST», уточните, в каком формате он его опишет: требование к документации от этого не исчезает.

Кто должен обновлять спецификацию API?

Спецификацию обновляет команда, которая меняет API, в том же изменении кода. Надёжнее, когда файл собирается из кода автоматически.

Почему Swagger UI на сайте лучше закрыть паролем?

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

Описание API в OpenAPI закладываем при разработке личного кабинета, где кабинет обменивается данными с 1С, CRM или приложением. Если API уже работает без документации, описываем его и доделываем при доработке существующего сайта.

Спецификация OpenAPI и документация Swagger

OpenAPI Specification, версия 3.2.1 (OpenAPI Initiative)
OpenAPI Initiative: часто задаваемые вопросы об истории спецификации
Документация Swagger: About OpenAPI, Swagger UI, Swagger Editor, Swagger Codegen

См. также: Тестирование сайта, gRPC.