Swagger — это популярный набор open-source инструментов, который помогает разрабатывать, документировать и тестировать REST API. Часто возникает путаница между терминами Swagger и OpenAPI. Давай проясним:
- OAS (OpenAPI Specification): Это сам стандарт формата описания API. Правила того, как описывать эндпоинты в YAML или JSON.
- Swagger: Это набор инструментов (Swagger UI, Swagger Editor), которые работают с этим форматом OAS и рисуют красивый интерфейс.
Зачем это нужно и почему это стандарт индустрии?
- API-First подход: Это супер-важная концепция. Вместо того чтобы бэкендеры писали код, а потом фронтендеры пытались под него подстроиться, команды сначала вместе садятся и проектируют контракт (Swagger-файл). Как только контракт утвержден, фронтендеры могут писать интерфейс на моках (заглушках), а бэкендеры — пилить реальную логику. Работа идет параллельно, сроки сокращаются вдвое.
- Единообразная документация: Документация в Wiki или Notion устаревает на следующий день после релиза. Swagger генерируется прямо из кода (или код из Swagger), поэтому он всегда актуален.
- Интерактивное тестирование: Swagger UI предоставляет кнопку «Try it out». Тебе не нужно открывать Postman или писать скрипты, чтобы дернуть ручку API — ты делаешь это прямо в браузере.