При проектировании современных программных систем часто встает задача согласования и разработки интерфейсов для взаимодействия их компонентов друг с другом.
В последнее десятилетие огромную популярность и развитие получили SPA и thick мобильные приложения взаимодействующие с сервером через API интерфейсы.
Если раньше разработка интерактивного веб сайта происходила путем поэтапных правок кода серверной стороны для генерации HTML разметки с ее последующей передачей браузеру клиента, то теперь разработка динамических веб приложений сместилась в сторону создания единого API сервиса и параллельной разработки множества приложений (в том числе и SPA) работающих с этим API как с главным источником данных.
Такой подход позволяет более удобно разделять задачи, организовывать команды, специализирующиеся только на конкретных технологиях (привлекать более узконаправленных специалистов), организовать параллельную разработку на самых первых этапах, а также позволяет создать единую точку коммуникации — API интерфейс.
Такая единая точка коммуникации требует формального и однозначного определения, этим документом является API спецификация.
Один из самых популярных протоколов для обмена сообщениями между (микро)сервисами — это REST
Проблема в том, что REST не является само описательным протоколом. Это значит, что клиент должен знать конкретную комбинацию URL, HTTP метода и формата ответа.
В некоторых случаях необходимо также знать также формат тела запроса. Обычно реализация REST интерфейса базируется на общих принципах и традициях, принятых в вашей организации.
В любом случае, REST endpoints всегда должны быть описаны в одном конкретном документе, доступном для всех остальных разработчиков.
Доменные модели прикладной области не обязательно должны совпадать с моделями, описанными в API-спецификации. Их возможные намеренные совпадения со структурами классов в коде клиентских приложений или со структурами схем БД вводятся скорее для упрощения процесса разработки.
Документацию должно быть легко читать, писать, парсить, генерировать, исправлять, обновлять и прочее.
Swagger — это фреймворк и спецификация для определения REST APIs в формате, дружественном к пользователю и компьютеру (в нашем случае JSON или YAML). Позже переименовался в OpenApi, но все продолжают использовать термин сваггер.
Но Swagger — это не просто спецификация. Основная его мощь заключается в дополнительных инструментах, вот некоторые примеры:
- swagger ui — на скрине выше. позволяет в наглядном виде просматривать документацию, отправлять запросы и получать реальные ответы.
- swagger-online — онлайн-редактор, wysiwyg
- swagger-php — позволяет генерировать документацию по комментариям из кода (например, к контроллерам и моделям)
Как это работает:
У каждого сервиса в определенной папке лежит файл со Swagger описанием и хранится это все прямо в git-репозитории. Описания могут быть как сгенерированы при помощи Swagger generator, так и записаны туда вручную.
Их легко распарсить, и во время сборки проекта мы можем автоматически проверять соответствие REST endpoints и документации.
Несоответствия будут генерировать предупреждения, и тем самым стимулировать разработчика поддерживать документацию в актуальном состоянии.
Плюс имеем версионирование документации по релизам приложения.
Поскольку каждый микросервис предоставляет собственную документацию, мы можем настроить специальную задачу для Дженкинса (или любого другого CI сервера), которая сгенерирует полную документацию для всего проекта.
Эта задача собирает Swagger файлы из всех микросервисов, производит некоторые минимальные модификации (дедупликация, удаление ненужных атрибутов) и на выходе генерирует единый Swagger файл, содержащий полную актуальную информацию для всего проекта.
Централизованное хранение и редактирование документации — это только первый шаг. Следующий — сделать ее доступной для всех разработчиков, тестеров и остальных заинтересованных людей в компании. И Swagger UI — это именно то, что вам для этого понадобится. При помощи небольшой JavaScript библиотеки Swagger UI генерирует HTML элементы для всех ваших REST endpoints, которые далее можно упорядочивать с помощью HTML разметки.
Альтернативы:
API Blueprint
RESTful API Modeling Language (RAML)
Заключение
Плюсы swagger:
- единая точка правды для всей команды
- фронтенд и бекенд могут выполняться параллельно, не ожидая друг друга и ориентируясь лишь на документацию
- автоматизация и тесты: при выполнении можно сверяться с документацией и выдавать ошибки в случае расхождений
- при быстрой разработке, когда сразу пишется код прототипа, есть возможность создавать документацию на ходу, описывая её в комментариях методов в DocBlock
- версионирование документации
- большая экосистема, позволяющая найти решение для любого языка программирования
- Понятный и легко читаемый язык описания
- Условно бесплатный хаб для спецификаций;
- Подробная официальная документация;
- Низкий порог вхождения.
Минусы:
- Порог входа для новых разработчиков все таки есть. Особенно при ручном написании документации
- Дополнительные трудозатраты на написание документации (на этапе проектирования, при быстрой разработке)
- Необходимость проектирования архитектуры заранее, что может осложнить последующие изменения
- не очень гибкая генерация ответов (призвольная пиганация, рандомные данные и т.д.)