Swagger (или Open API) — это спецификация и набор инструментов для проектирования, построения, документирования и использования RESTful веб-сервисов.
Основные компоненты:
- Спецификация OpenAPI (OAS): Языково-независимый формат описания RESTful API в виде JSON или YAML. Описывает доступные эндпоинты, параметры, ответы, схемы данных, авторизацию и метаданные.
- Swagger UI: Инструмент для визуализации и интерактивного взаимодействия с API, описанным в спецификации OpenAPI. Позволяет просматривать документацию и выполнять запросы прямо из браузера.
- Swagger Codegen: Набор инструментов для автоматической генерации серверного кода (скелетов) и клиентских SDK на основе спецификации OpenAPI.
Преимущества использования:
- Единая документация: Создает стандартизированную и всегда актуальную документацию для API.
- Разработка по контракту: Позволяет командам бэкенда и фронтенда работать параллельно, договорившись о контракте API.
- Автоматизация тестирования: Используется для автоматической генерации тестов API (например, с помощью Swagger Inspector).
- Обнаружение API: Упрощает поиск и понимание доступных API в системе.
Пример части спецификации в YAML:
yaml