Swagger

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

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

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

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

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

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