Swagger

Swagger — это программная среда с открытым исходным кодом, поддерживаемая большой экосистемой инструментов, которая помогает разработчикам проектировать, создавать, документировать и использовать веб-сервисы RESTful

Описание

Swagger — это фрэймворк для описания, документирования и визуализации REST API. На основании спецификации Swagger можно генерировать исходный код для библиотек клиентских приложений, текстовую документацию для пользователей, варианты тестирования и др. Для этого имеется множество инструментов для различных языков программирования и платформ.

Инструмент представляет собой языконезависимую утилиту. Это значит, что Swagger создаёт чёткую документацию, которая читается одинаково хорошо как человеком, так и машиной, позволяя автоматизировать процессы зависящие от API.

Принцип работы

  • У каждого сервиса в определенной папке лежит файл со Swagger описанием и хранится это все прямо в git-репозитории. Описания могут быть как сгенерированы при помощи Swagger generator, так и записаны туда вручную. Их легко распарсить, и во время сборки проекта мы можем автоматически проверять соответствие REST endpoints и документации.
  • Несоответствия будут генерировать предупреждения, и тем самым стимулировать разработчика поддерживать документацию в актуальном состоянии.
  • Плюс имеем версионирование документации по релизам приложения.
  • Поскольку каждый микросервис предоставляет собственную документацию, мы можем настроить специальную задачу для Дженкинса (или любого другого CI сервера), которая сгенерирует полную документацию для всего проекта.
  • Эта задача собирает Swagger файлы из всех микросервисов, производит некоторые минимальные модификации (дедупликация, удаление ненужных атрибутов) и на выходе генерирует единый Swagger файл, содержащий полную актуальную информацию для всего проекта.

 

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

  • Единая точка правды для всей команды
  • Фронтенд и бекенд могут выполняться параллельно, не ожидая друг друга и ориентируясь лишь на документацию
  • Автоматизация и тесты: при выполнении можно сверяться с документацией и выдавать ошибки в случае расхождений
  • При быстрой разработке, когда сразу пишется код прототипа, есть возможность создавать документацию на ходу, описывая её в комментариях методов в DocBlock
  • Версионирование документации
  • Большая экосистема, позволяющая найти решение для любого языка программирования
  • Понятный и легко читаемый язык описания
  • Условно бесплатный хаб для спецификаций;
  • Подробная официальная документация;
  • Низкий порог вхождения.
  • Документация API
    ...
  • Документирование REST API
    ...

Аналоги и альтернативы для Swagger

Swagger - похожие продукты (инструменты, решения, сервисы)

Интеграции для Swagger

Смотреть все интеграции с Swagger

Отзывы

Отзывов пока нет.

Будьте первым, кто оставил отзыв на “Swagger”

Ваш адрес email не будет опубликован. Обязательные поля помечены *