Перейти к основному содержимому

Swagger

Swagger — набор инструментов для создания, документирования и тестирования RESTful API. Основой Swagger является формат OpenAPI, который позволяет описывать API на уровне спецификаций.

Зачем нужен?​

  • Автоматическая генерация интерактивной документации
  • Тестирование API в реальном времени
  • Единый стандарт (OpenAPI) для совместимости между различными системами и командами
  • Автоматизация создания клиентских SDK и серверных частей

Возможности​

  • Интеграция с инструментами для авто-тестирования (Postman и др.), создание тестов на основе спецификаций API
  • Поддержка версионирования спецификаций API
  • Широкая экосистема: множество плагинов, инструментов и расширений для различных нужд
  • Добавление информации о безопасности API, включая поддержку OAuth2, JWT и других механизмов аутентификации и авторизации

Из чего состоит?​

Swagger Core​

Ядро Swagger, программная реализация спецификации OpenAPI 3.0.

Swagger Editor​

Веб-инструмент для создания и редактирования спецификаций OpenAPI:

  • Подсветка синтаксиса и автодополнение
  • Встроенная валидация спецификаций
  • Работа с YAML и JSON форматами
  • Экспорт / импорт спецификаций

Swagger UI​

Интерактивная документация, которая генерируется на основе спецификаций API:

  • Тестирование API вызовов
  • Поддержка авторизации (Bearer, Basic Auth, API Key)
  • Визуальное отображение структуры API
  • Встроенная поддержка для описания моделей данных

Swagger Codegen​

Инструмент для автоматической генерации клиентских SDK и серверных частей на основе спецификаций OpenAPI:

  • Поддержка разных языков программирования и фреймворков (Java, Python, C#, Ruby и др.)
  • Генерация клиентских библиотек, серверных стубов и документации
  • Настраиваемые шаблоны для генерации кода
  • Интеграция с CI/CD процессами

С чего начать работу со Swagger?​

  1. Создать спецификацию API в Swagger Editor
  2. Сохранить в формате JSON или YAML
  3. Открыть в Swagger UI, чтобы визуализировать и тестировать API
  4. Использовать Swagger Codegen для генерации кода клиента или сервера

Подходы к созданию API​

Code First​

Спецификации API генерируются на основе кода. Используется:

  • Когда необходимо быстро создать API
  • Для создания прототипов и экспериментальных проектов
  • Когда добавляются API к уже существующим кодовым базам

Преимущества​

  • Легко и быстро внедрить, не требует первоначального знания спецификаций

Недостатки​

  • Документация может отставать от кода, сложнее поддерживать в долгосрочной перспективе

Пример реализации​

  • Swagger annotations (Java) / атрибуты (C#): добавление документации в код
  • Swagger-Core (Java)/ Swashbuckle (C#): генерация спецификаций

Contract First (API First)​

Спецификации создаются до написания кода. Используется:

  • Для обеспечения согласованности и стандартизации
  • Когда несколько команд работают над разными частями системы
  • Для детальной проработки API до начала разработки

Преимущества​

  • Высокая согласованность и понятность, легче поддерживать

Недостатки​

  • Требует больше усилий на этапе проектирования

Пример реализации​

  • Editor: создание спецификаций API в формате OpenAPI
  • Codegen: генерация серверных шаблонов и клиентских библиотек по спецификациям

Примеры расширений и плагинов​

  • SwaggerHub: Платформа для совместной работы над спецификациями API в реальном времени
  • SwaggerHub Explorer: Инструмент для тестирования API без необходимости писать код
  • Swagger Validator: Проверка спецификации на наличие ошибок и соответствие стандартам

Отличие от Postman​

Цель​

  • Swagger ориентирован на проектирование и документирование API
  • Postman — на тестирование и отладку

Функции​

  • Swagger позволяет создавать спецификации и генерировать код
  • Postman фокусируется на тестировании, хранении запросов и автоматизации тестов

Подборка материалов для поста про Swagger​

  1. Кратко про Swagger
  2. OpenAPI/Swagger для начинающих
  3. Как Swagger облегчает работу системного аналитика с API
  4. Знакомимся со Swagger на примере собственного веб-приложения с REST API
  5. Swagger: что это и как работать с документацией
  6. Спецификации OpenAPI и Swagger
  7. Обзор руководства OpenAPI 3.0
  8. Практическое занятие "Создание спецификации OpenAPI"
  9. Проектирование спецификации OpenAPI
  10. API-First и микросервисы

Видео​

  1. Кратко про OpenAPI и Swagger
  2. Что такое Swagger и OpenAPI за 3 минуты
  3. API-first-подход в межсервисном взаимодействии
  4. Как аналитику спроектировать свой REST API
  5. API + Swagger - Игорь Гусев
  6. Что такое Contract First подход за 4 минуты
  7. Что такое Code First подход за 4 минуты

Конференции​

  1. Analystdays: Specification-first подход в разработке API
  2. Analystdays: Разработка и управление едиными контрактами API
  3. Analystdays: API-First и UI-First. Противостояние

Книги​

  1. API — Сергей Константинов Читать
  2. Тестирование веб-API — Марк Винтерингем Читать