Что такое OpenAPI (Swagger) и как вы используете его в работе аналитика?
Короткий ответ
- OpenAPI — стандарт описания REST API в YAML или JSON
- Описывает эндпоинты, методы, параметры, схемы, коды ответов
- Swagger UI даёт интерактивную документацию и возможность дёрнуть метод
- Contract-first: сначала спецификация, потом разработка
- По спецификации генерируют код, моки и тесты
- Единый источник правды для бэкенда, фронтенда и QA
OpenAPI — стандартный машиночитаемый контракт REST API, который аналитик пишет или согласует как единый источник правды для разработки, тестирования и интеграций.
Как сказать вслух
пример ответаOpenAPI — это стандарт описания REST API в виде YAML или JSON файла: какие есть эндпоинты, методы, параметры, структуры запросов и ответов, коды ошибок. Swagger — это экосистема инструментов вокруг него, например Swagger UI, где документацию можно читать и сразу пробовать запросы. Я использую его как контракт: описываю API до разработки, согласую с командой и контрагентом, дальше по нему пишут код и тесты. Это снимает споры о том, «как договаривались».
Подробный ответ
Основной ответ
OpenAPI Specification — стандарт машиночитаемого описания REST API (актуальны версии 3.0/3.1). Файл в YAML или JSON описывает пути и операции, параметры (path, query, header), тела запросов и ответов через JSON Schema в блоке components, коды состояния, схемы авторизации, примеры. Swagger — исторически название стандарта и ныне набор инструментов: Swagger UI (интерактивная документация), Editor, Codegen. Для аналитика это инструмент контракта: при подходе contract-first спецификация пишется и согласуется до кода, что позволяет фронтенду и контрагентам работать параллельно по мокам, сгенерированным из неё, а QA — строить тесты на контракт. Переиспользование схем через $ref держит описание консистентным. Спецификация версионируется вместе с кодом, и её изменения проходят ревью как изменения контракта.
Ключевые моменты
- Contract-first. Спецификация до кода: команды работают параллельно, контрагент подключается по мокам, споры о формате решаются до разработки.
- Структура описания. Paths и операции, parameters, requestBody, responses с кодами, components со схемами и переиспользованием через $ref.
- Коды и ошибки. Аналитик описывает не только 200, но и 400, 401, 404, 409, 500 с форматом тела ошибки.
- Генерация артефактов. Из спецификации генерируют клиентский и серверный код, моки и контрактные тесты — ошибки контракта ловятся рано.
Практический контекст
В большинстве продуктовых команд системный аналитик либо сам пишет OpenAPI-спецификацию, либо ревьюит написанную разработчиком. На собеседовании могут показать фрагмент YAML и попросить объяснить его или найти проблему — например, отсутствие описания ошибок. Ценится понимание contract-first подхода и привычка описывать негативные ответы, а не только успешный сценарий.
Частые ошибки
- Называют Swagger «программой для документации», не понимая идею контракта
- Описывают только успешный ответ 200 без ошибок и их формата
- Не версионируют спецификацию, из-за чего контракт расходится с реализацией