С увеличением роста разрабатываемых проектов компании сталкиваются с созданием и использованием технической документации к API. Более 90% респондентов считают: критически важная трудность для бизнеса состоит в унифицировании процесса разработки API и документации по нему, а также сделать их доступными для всех продуктовых команд в корпоративной базе.
Один из инструментов, решающих эту проблему — Swagger. Эта платформа позволяет создавать документацию не только в формате JSON, но и в YAML.
Что такое Swagger
Swagger простыми словами — инструмент для подготовки документации к API (вроде нашей) и проведения тестов API. Он позволяет программистам, техническим писателям и тестировщикам быстрее создавать, описывать и проверять программный интерфейс.
Инструмент поддерживает спецификацию OpenAPI, которая набор формальных плавил, которые нужно использовать при описании API в формате JSON или YAML Swagger позволяет автоматически генерировать клиентский код для всех популярных языков программирования и данные для тестирования. Например, модели данных, примеры запросов и ответов, а также базовые тестовые сценарии и проверки, основанные на спецификации API.
Swagger стал популярнее других фреймворков и сервисов для создания документации, потому что он предлагает удобочитаемый формат. В нём без проблем разберётся как человек, так и машина. Swagger — это многофункциональная платформа, которая сокращает время реализации проекта.
Чтобы работать с веб-GUI Swagger тестируемого приложения, построенного на базе REST API, софт разворачивают в SwaggerHub. Это многопользовательская площадка, позволяющая определять REST API через спецификации и управлять ими.
Как работает Swagger
Swagger (особенно в контексте OpenAPI) использует модели данных, примеры запросов и ответов, а также базовые тестовые сценарии и проверки, основанные на спецификации API. А также комплекс правил для формы описания REST API. Инструмент применяют для генерации документации в виде JSON-файла и совместной работы с ней. Документация создаётся не напрямую, а на основе описания структуры и функций API.
Одна из особенностей Swagger — готовый шаблон. В нём прописаны все компоненты API по ключевым словам. Они находятся в разных блоках, поэтому пользователь может быстро найти интересующий фрагмент. Не все компании в России используют Swagger, часть разработчиков считает готовый шаблон «школьной поделкой» и утверждает, что клиент должен получить более удобное описание программного интерфейса.
Основное преимущество Swagger в том, что он предоставляет стандартизированный способ описания API, что позволяет разработчикам и системам легко интерпретировать и использовать эту информацию.
Компоненты Swagger
Swagger состоит из четырёх компонентов. Есть ещё несколько, но их не так часто применяют в работе.
Swagger Core
Swagger Core — это ядро инструмента и реализация спецификации OpenAPI 3.0. С его помощью разработчики могут создавать и документировать API в соответствии с этой спецификацией. Для работы с Swagger Core рекомендуется использовать Java версии 8.0 или выше.
Чтобы нормально работать с определенными версиями или конфигурациями Swagger, пользователю потребуются Java не ниже версии 8.0.
После внедрения ядра Swagger разработчики смогут автоматизировать написание документов на базе готового кода.
На этапе сборки проекта происходит автоматическая генерация документации API на основе аннотаций Swagger, размещенных в исходном коде, а также множество других связанных задач.
Обширность документации зависит от многих факторов, включая сложность самого API и степень детализации, которую разработчик хочет предоставить.
Swagger UI
Этот компонент Swagger используют для визуализации документации. Благодаря ему документация API становится более читаемой, визуально привлекательной и интерактивной для пользователей. Swagger UI создаёт интерактивные шаблоны, для работы с которыми не нужно использование кода. Все манипуляции выполняют посредством интерфейса.
Компонент позволяет генерировать и направлять различные запросы для тестирования API и обеспечивает удобную навигацию по документации". Таким образом, акцент делается на удобстве использования интерфейса, а не на перемещении по разным файлам. Созданный UI интегрируют в программу и публикуют на странице в браузере. Swagger UI поддерживается большинством современных веб-обозревателей.
Swagger Codegen
Третий компонент инструмента — генератор кода, позволяющий автоматически создать программный код для решения типовых задач. Решение Swagger не заменит программиста, но может облегчить выполнение проекта, избавив от рутинных действий. Swagger Codegen позволяет автоматически генерировать:
-
Серверные заглушки, которые служат точками входа для взаимодействия внешних систем с вашим API.
-
Клиентские библиотеки, которые предоставляют инструменты для разработки приложений, взаимодействующих с вашим API.
Документацию на основе сгенерированного кода.
Компонент Swagger Codegen поддерживает много языков программирования, поэтому его можно внедрять для работы практически с любыми проектами. Swagger может генерировать код на различных языках на основе спецификации API:
-
Java. Разработчики Swagger предусмотрели поддержку фреймворков для этого языка
-
C++
-
PHP
-
Python
-
Ruby
-
Rust
Кроме того, генератор документации работает с HTML, и сгенерированную информацию можно использовать в Confluence — платформе для корпоративных баз знаний.
Используйте генератор кода с осторожностью и проверяйте получившиеся фрагменты. Инструмент предлагает типовыее решения, не учитывая специфики, из-за чего могут возникнуть баги и трудности с оптимизацией.
Swagger Editor
Swagger Editor — это инструмент для редактирования и просмотра спецификаций OpenAPI в режиме реального времени. Существует веб-версия и версия для установки на компьютер. При этом он не "встроен" в какое-то конкретное приложение или платформу, но часто интегрируется с различными системами для удобства работы разработчиков. Пользователь может смотреть составленные правила и дополнять их. Есть две версии редактора:
-
Браузерная.
-
Для установки на компьютер. Она может предоставлять дополнительные возможности или интеграцию, отличающуюся от браузерной версии.
Визуально и по количеству функций они не отличаются, поэтому выбор между ними — дело вкуса. Редактор имеет два окна:
-
Слева находится поле для создания кода описания программного интерфейса.
-
Справа — окно генерирования визуального интерфейса в Swagger UI. Он сразу становится интерактивным. Пользователь, не закрывая Editor, может проверить оформление документа и протестировать его.
В редактор встроена система для проверки кода на соответствие требованиям. Если пользователь допустил ошибку, система пометит строку в режиме реального времени.
Кто пользуется Swagger
Swagger стал популярным инструментом в сфере разработки API, так как он упрощает процесс создания и документирования API. Этим инструментом активно пользуются разработчики, технические писатели, аналитики и другие специалисты, которым требуется глубокое понимание проекта.
Задачи, которые решает Swagger:
-
Документация API. Главная функция инструмента — документации в JSON-формате, которые будут читабельны как для специалистов, так и для ПК. Swagger внедряют для максимально быстрого документирования программного кода. Его обычно используют для работы с архитектурой REST API.
-
Разработка программного интерфейса. Инструмент используют, когда нужно проверить соответствие готового продукта с документацией и автоматизировать написание кода на основе спецификаций. Это упростит поиск нереализованных функций и доработку проекта. Встроенный Swagger Codegen поможет составить рабочий код по подготовленным документам.
-
Swagger UI преобразует описания API в интерактивную документацию. Это позволяет разработчикам легко тестировать API прямо из браузера и ускоряет процесс понимания и изучения проекта.
Тестирование API
Кейс Exolve
К платформе Exolve подключился разработчик онлайн-игр, который хотел упростить авторизацию для сотрудников и повысить защиту корпоративных систем. Для решения этой проблемы есть готовый модуль авторизации. Он позволяет:
-
Настроить двухфакторную аутентификацию или вход по SMS.
-
Создать индивидуальный токен для каждого пользователя.
У компании есть свои разработчики, которые хотели перед внедрением проверить безопасность и надёжность кода. Мы отправили им доступ к документации в Swagger, а также ссылку на форум с разбором основных функций.
Результаты интеграций: вход в корпоративные приложения и базы данных стал быстрее и безопаснее, поскольку API не хранит пароли, в отличие от ранее используемого IT-решения.
Плюсы и минусы использования Swagger
У Swagger пять ключевых преимуществ:
-
Экономия времени и быстрая реализация проекта благодаря инструментам для тестирования софта и готовым шаблонам.
-
Минимизация рутины. Codegen может создавать код по шаблону за несколько секунд. Команде разработки не придётся тратить силы на рутину.
-
Прозрачность документов. Готовые файлы получаются понятными и доступными для любых читателей — разработчиков, компьютеров и простых пользователей.
-
Гибкость. Со Swagger можно автоматически написать документы с опорой на код или вручную, применять различные средства визуализации для навигации и проведения проверок без использования кода.
-
Универсальность. Документы Swagger интегрированы в сайт или программу. При этом она останется интерактивной.
Из объективных недостатков инструмента — отсутствие выделять ключевые части текста, добавлять интерактивные сноски и быстрые ссылки. Swagger использует спецификацию OpenAPI, которая позволяет создавать структурированную и хорошо организованную документацию. OpenAPI и Swagger UI поддерживают Markdown для стилизации описаний. Разработчики часто используют Markdown и аналогичные средства для оформления документации, что позволяет помечать ключевые части, оставлять интерактивные сноски в файле и ссылки для быстрого перемещения. В Swagger подобных функций нет.
В результате страдает читабельность документации API.
Некоторые специалисты в сфере IT принципиально избегают использования Swagger, считая его избыточным или неэффективным. В профессиональном сообществе существует мнение, что Swagger может усложнять понимание взаимодействия между backend (серверной частью) и frontend (клиентской частью). Ещё немного деталей:
Абстракция: Swagger предоставляет высокоуровневое представление о том, как API должен функционировать. Некоторые разработчики считают, что это создает дополнительный слой абстракции, который может затруднять понимание тонкостей реального взаимодействия между клиентом и сервером.
Автоматизация: в то время как автоматическая генерация кода с помощью Swagger может ускорить разработку, она также может привести к тому, что разработчики становятся менее знакомыми с реальным кодом и его функционированием.
Дополнительные зависимости: внедрение Swagger добавляет дополнительные зависимости и шаги в процесс разработки. Это может внести дополнительную сложность, особенно для команд, которые ранее не использовали подобные инструменты.
Стандартизация: хотя стандартизация может быть полезной, она также может привести к потере гибкости. Некоторые разработчики считают, что следование стандартам Swagger ограничивает их возможности и делает систему менее адаптивной.
Усложнение коммуникации: если команда разработчиков уже имеет устоявшиеся процессы коммуникации и документирования, внедрение Swagger может потребовать изменения этих процессов, что может вызвать недопонимание или даже сопротивление.
Такая точка зрения справедлива. Swagger создаёт документацию на основе существующего кода или спецификации OpenAPI. Инструмент слишком стандартизирован и не учитывает индивидуальных потребностей. Это может стать проблемой при работе со сложными и комплексными экосистемами.
Аналоги Swagger
Кроме Swagger разработчики активно используют множество средств для документирования REST API. Рассмотрим три основных аналога:
Redocly
Процесс создания документов для RESTful API автоматизировали с помощью Redocly Workflows. Сервис позволяет редактировать файлы вместе с коллегами и включает инструменты для автоматической генерации интерактивной документации на базе OpenAPI. Для защиты корпоративных проектов создатели предусмотрели проверку попыток, систему аутентификации и другие механизмы.
ReadMe
Благодаря ReadMe техническая документация становится динамическим центром продуктовой команды. Разработчики могут создавать примеры кода, изменять фрагменты, написанные другими, рекомендовать правки и общаться на форуме.
ReadMe имеет встроенную аналитику, сохраняет информацию о посещениях, запросах и отказах. Инструменты и данные помогут понять, как используется API и техдокументы после выпуска продукта.
apiDoc
Это функциональное решение для документирования с открытым программным кодом. Оно использует спецификации API для автоматической генерации документации. Инженеры и другие участники проекта могут отслеживать, что изменили между выпусками API, и при желании откатить последние обновления.
Заключение
Swagger позволяет создавать REST API быстрее и с минимумом рутины. Существует множество способов написания документации по API, но есть стандарт, которому нужно следовать, и инструменты, гарантирующие, что всё останется на одной странице. Если вы ещё не внедрили инструмент управления для своей документации API, такой как Swagger, вам определённо следует подумать об этом.