Swagger и OpenAPI: как описать API, чтобы фронтенд, тестировщик и аналитик поняли его сразу
OpenAPI — это формат файла в YAML или JSON, в котором API описан целиком: какие есть адреса и методы, какие параметры и тело принимает каждый запрос, какие ответы и ошибки возвращаются, как устроена авторизация. Swagger — набор инструментов вокруг этого формата: в Swagger Editor описание пишут и проверяют, Swagger UI превращает его в интерактивную страницу, Swagger Codegen и его форк OpenAPI Generator создают по нему код клиента и заготовку сервера. Начинать удобно, когда уже понятны HTTP и JSON. Дальше — учебный пример, правила описания доступа, порядок освоения, типичные ошибки и обучение.
Содержание

Частое заблуждение: «Swagger — это страница /docs, которая сама появляется у бэкенда». Страница может генерироваться из кода, но ценность формата в другом. Файл OpenAPI — это договор между командами. Фронтенд-разработчик по нему пишет вызовы до того, как сервер готов, тестировщик заранее знает, какой ответ считать правильным, аналитик видит, все ли сценарии учтены. Если договор написан небрежно, каждый поймёт его по-своему, и расхождение всплывёт только на стыке.
Что внутри файла OpenAPI
Документ начинается со строки openapi с номером версии формата и блока info с названием и версией самого API. В servers перечисляют адреса окружений. Главная часть — paths: для каждого пути и метода указывают параметры, тело запроса и ответы по кодам состояния. Повторяющиеся куски выносят в components: схемы данных, типовые ответы, описания способов авторизации. На них ссылаются через $ref, чтобы одна схема «Бронирование» не дублировалась в десяти местах.
Раньше Swagger назывался и сам формат; с версии 3.0 он называется OpenAPI, а имя Swagger осталось за инструментами. Сейчас развиваются ветки 3.1 и 3.2: версия 3.2.1 опубликована 10 сентября 2026 года. Генераторы поддерживают версии неодинаково, поэтому номер в первой строке выбирают под инструменты команды.
Кому и когда это нужно
Бэкенд-разработчик описывает в OpenAPI то, что сервис обещает, и по той же схеме может проверять входящие запросы. Фронтенд-разработчик генерирует типизированный клиент и поднимает заглушку сервера, которая отвечает примерами из файла. Тестировщик строит проверки по схеме: обязательные поля, границы чисел, допустимые значения, ожидаемые коды ошибок. Системный аналитик пишет контракт до разработки и согласует его со всеми сторонами.
Формат подходит для HTTP API в стиле REST. Если команда выбрала GraphQL, контрактом служит его собственная схема, для gRPC — файлы protobuf, а для обмена событиями через брокер существует отдельный формат AsyncAPI. Postman, FastAPI и JWT на сайте разобраны в отдельных статьях; здесь речь о самом описании.
Учебный пример: метод «создать бронирование»
Ситуация учебная. Сервис бронирования переговорных комнат должен принимать заявку и возвращать созданную бронь. Аналитик описывает метод до того, как бэкенд начал работу:
paths:
/bookings:
post:
operationId: createBooking
summary: Создать бронирование
requestBody:
required: true
content:
application/json:
schema: { $ref: '#/components/schemas/BookingRequest' }
responses:
'201': { $ref: '#/components/responses/BookingCreated' }
'400': { $ref: '#/components/responses/ValidationError' }
'409': { $ref: '#/components/responses/RoomBusy' }
operationId станет именем метода в сгенерированном клиенте. Поля тела — комната, начало, конец — описаны в схеме BookingRequest с типами и форматами. Кроме успешного ответа 201 перечислены две ошибки: 400 — когда поля заполнены неверно, 409 — когда комната уже занята. Фронтенд видит, что нужно сообщение «время занято», а тестировщик — что нужен сценарий с пересечением броней.
Авторизация в описании: список работает как «или»
Больше всего недоразумений связано с полем security. По спецификации OpenAPI 3.1.1 это список альтернатив: чтобы запрос был авторизован, достаточно выполнить одно из требований в списке. Внутри одного требования схемы складываются через «и». В документации Swagger по аутентификации правило сформулировано коротко: элементы словаря объединяются логическим «и», элементы массива — логическим «или».
На практике это выглядит так. Команда хочет, чтобы клиент передавал и токен пользователя, и ключ приложения. Если записать две строки — - bearerAuth: [] и - apiKey: [], — получится описание «токен или ключ». Правильно — один элемент списка с двумя ключами: строка - bearerAuth: [], а под ней apiKey: [] с тем же отступом, что у bearerAuth. Ошибка не ломает файл, валидатор её не заметит, зато фронтенд и сгенерированный клиент решат, что хватит чего-то одного.
Два других правила касаются отдельных методов. security на уровне операции не дополняет общее требование, а заменяет его: по спецификации 3.2.1, чтобы снять авторизацию с метода, пишут пустой массив security: []. А пустой объект {} внутри списка делает авторизацию необязательной. Там же сказано, что список может быть неполным и даже отсутствовать. Значит, описание в OpenAPI — обещание для читателей, а не защита: проверять токен всё равно обязан сервер, и тестировщику стоит отдельно убедиться, что метод без security в описании действительно закрыт там, где это нужно.
Design-first или code-first
При подходе code-first описание генерирует фреймворк по коду: документация не отстаёт от реализации, но контракт появляется только вместе с сервером, и фронтенд ждёт. При подходе design-first команда сначала пишет и обсуждает файл OpenAPI, затем по нему делают заглушку, клиент и тесты, а сервер обязан ему соответствовать. Разногласия всплывают на ревью документа, а не после релиза.
Design-first оправдан, когда API пользуются несколько команд или внешние партнёры, когда фронтенд и бэкенд работают параллельно, когда изменение контракта дорого. Для небольшого внутреннего сервиса одного разработчика проще code-first. Подходы совмещают: метод проектируют в файле, а автотест сверяет с ним описание, сгенерированное из кода.
С чего начать и в каком порядке осваивать
Порядок ниже идёт от чтения к письму и затем к автоматизации. Сначала нужно научиться понимать чужое описание, потом написать своё, и только когда оно стало точным, имеет смысл генерировать по нему код и тесты: генератор и контрактные тесты повторят любую неточность.
- Откройте демонстрационное описание Petstore в Swagger Editor, найдите путь, параметры, схему ответа и попробуйте отправить запрос из Swagger UI.
- Опишите один метод
GETсвоего учебного сервиса: путь, параметр, ответ 200 и ответ 404. - Вынесите схемы в
componentsи подключите их через$ref, добавьте обязательные поля, форматы и ограничения. - Опишите ошибки единым форматом, например по RFC 9457, и задайте авторизацию через
securitySchemes. - Проверьте файл линтером, например Spectral или Redocly CLI, и исправьте замечания.
- Сгенерируйте клиент через OpenAPI Generator и поднимите заглушку сервера, затем напишите проверку, что ответы реального сервиса совпадают со схемой.
Если хочется пройти этот путь с наставником и сделать контракт частью портфолио, на онлайн-курсе Skillbox «Системный аналитик + ИИ» за восемь месяцев есть блок «Архитектура, API и базы данных»: HTTP, REST, SOAP, диаграммы последовательности, проектирование API, чтение OpenAPI-документации и работа со Swagger и Postman, а среди девяти работ портфолио указан OpenAPI-документ.
Типичные ошибки и как себя проверить
Чаще всего новички описывают только успешный ответ. Читатель контракта не узнаёт, что придёт при неверных данных или нехватке прав, и каждый клиент обрабатывает ошибки наугад. Вторая ошибка — примеры, которые не соответствуют схеме: в схеме дата в формате date-time, а в примере строка «завтра». Третья — путаница между необязательным полем и полем, которое может прийти как null: это разные вещи, и в схеме их задают по-разному.
Есть и формальные ловушки. Спецификация требует, чтобы operationId был уникальным среди всех операций: генератор строит из него имена методов, и дубль приводит к конфликту. Пути /users/{id} и /users/{login} с одной структурой и разными именами параметров тоже запрещены — по правилам формата они идентичны: адрес /users/42 подходит под оба.
Лучшая самопроверка — отдать файл человеку, который не видел сервис, и попросить написать по нему вызов: каждый его вопрос показывает пробел в описании.
Чему учат на курсах
Обычно OpenAPI входит в программы для аналитиков, бэкенд-разработчиков и тестировщиков, поэтому смотрите на задания: пишете ли вы спецификацию сами и проверяет ли её наставник.
Для бэкенд-разработчика подойдёт программа, где спецификация связана с кодом. На онлайн-курсе Нетологии «Java-разработчик» за 11 месяцев в блоке серверной разработки проходят REST, Spring и Spring Boot, хранение данных и безопасность, а Swagger и OpenAPI используют, чтобы зафиксировать контракт сервиса. Поурочный план и объём темы уточните у школы.
Аналитику полезно увидеть контракт рядом с архитектурой — очередями, событиями, разбиением на сервисы, — чтобы понимать, когда хватает REST и OpenAPI, а когда нужен асинхронный обмен со своим форматом описания.
Такую связку разбирают на онлайн-курсе Яндекс Практикума «Системный аналитик расширенный»: программа рассчитана на девять месяцев, а в расширенной части есть высокоуровневое проектирование API, Query-Based API, AsyncAPI и описание Swagger в YAML. Курс подойдёт тем, кто уже понимает базовые диаграммы.
Как навык влияет на доход
Знание Swagger и OpenAPI редко оплачивается отдельно: это строка в требованиях к аналитику, тестировщику или бэкенд-разработчику. Среди первых десяти вакансий по запросу «Swagger» на Хабр Карьере 15 октября 2026 года было четыре вакансии тестировщиков, три — системных аналитиков и две — Java-разработчиков.
По калькулятору зарплат Хабр Карьеры на октябрь 2026 года медиана у специалистов, указавших навык Swagger, — 177 400 ₽ в месяц, у middle — 170 050 ₽, но выборка всего 35 анкет, у middle — 16. Для сравнения, по системным аналитикам медиана — 222 500 ₽ по 2 459 анкетам, у middle — 196 666 ₽. Это зарплаты, которые указали сами пользователи за скользящие полгода, без фильтра по региону (методика), а не предложения работодателей. Доход определяют профессия и уровень, а умение писать контракт помогает брать задачи по интеграциям.
Если вы выбираете обучение бэкенду, сравнить школы по цене и формату поможет общий рейтинг онлайн-школ по бэкенд-разработке. Он широкий и охватывает разные языки и фреймворки, поэтому программы с OpenAPI придётся искать по описанию. А до оплаты попробуйте описать в Swagger Editor один метод сервиса, которым пользуетесь каждый день, и покажите файл коллеге: по его вопросам станет ясно, с чего продолжать.