Swagger — набор открытых инструментов и спецификаций для разработки, проектирования, документирования и использования RESTful API. Изначально созданный как описание для автоматизации генерации документации и клиентских SDK, Swagger эволюционировал в экосистему инструментов, позволяющую описывать интерфейсы в машинно-читаемом формате, тестировать их и генерировать код. Технологии, связанные со Swagger, применяются для упрощения взаимодействия между разработчиками, автоматизации проверки контрактов и ускорения процессов интеграции.
Ключевой компонент — спецификация, которая формализует описание конечных точек, методов, схемы запросов и ответов, типов данных, параметров и кодов ошибок. На её основе работают визуальные редакторы, интерактивные интерфейсы для изучения API, генераторы серверной и клиентской части, а также инструменты для тестирования и валидации. Спецификация совместима с широким набором языков и фреймворков, что делает её популярной в корпоративных и открытых проектах.
- Формальная спецификация: машинно-читаемое описание API, включая пути, методы, параметры, тела запросов и схемы ответов.
- Документация в интерактивном виде: автоматически генерируемые интерфейсы для изучения и тестирования эндпоинтов в реальном времени.
- Генерация кода: инструменты для автоматического создания клиентских SDK и заготовок серверной логики на различных языках программирования.
- Валидация и тестирование: средства для проверки соответствия реализации API его спецификации и для автоматизированного тестирования сценариев.
- Интеграция с CI/CD: возможности встроить проверки спецификации и генерацию артефактов в процессы непрерывной интеграции и доставки.
- Поддержка форматов: совместимость с JSON и YAML для удобства редактирования и сериализации описаний API.
- Расширяемость: механизмы добавления метаданных и расширений для описания нестандартных аспектов API и интеграции с другими инструментами.