Ранее, в качестве способа визуализации документа спецификации OpenAPI, мы изучили опен-сорс проект Swagger UI. Та же компания, которая предлагает бесплатную версию Swagger Editor и Swagger UI (Smartbear), также предлагает премиум-версию с более надежными функциями. Эта премиальная версия редактора Swagger называется SwaggerHub. Разницу этих проектов можно увидеть здесь.
Пример OpenWeatherMap API на SwaggerHub можно посмотреть здесь
Преимущества SwaggerHub
Несмотря на то, что редактор Swagger в сочетании со Swagger UI работает, могут возникнуть проблемы такого плана:
- сложно сотрудничать с другими участниками проекта по спецификации;
- трудно собрать отзывы от рецензентов о конкретных частях спецификации;
- не получится автоматически предоставлять API в бесчисленных структурах кода, где им бы были рады.
При работе с документацией API REST, нужны инструменты, специально разработанные для API-интерфейсов - инструменты, которые позволяют создавать, совместно использовать, совместно работать, создавать версии, тестировать и публиковать документацию способами, не требующими значительной настройки или времени.
В какой-то момент эксперименты с бесплатным инструментом Swagger UI встречают преграду, и нужно найти другой способ для перехода на следующий уровень. Следующий уровень - это SwaggerHub от Smartbear. SwaggerHub предоставляет полное решение для проектирования, управления и публикации документации API способами, которые упрощают жизнь технического писателя API.
Более 15 000 команд разработчиков программного обеспечения по всему миру используют SwaggerHub. Поскольку спецификация OpenAPI становится в большей степени отраслевым стандартом для документации API, специфичные инструменты SwaggerHub имеют важное значение.
Вступление SwaggerHub и его Дэшборд
Smartbear - это компания, которая поддерживает и разрабатывает инструменты Swagger с открытым исходным кодом (Swagger Editor, Swagger UI, Swagger Codegen и др.). Они также сформировали инициативу OpenAPI, которая ведет эволюцию спецификации Swagger (OpenAPI).
Smartbear разработал SwaggerHub как способ помочь командам совместно работать над спецификацией OpenAPI. Многие из клиентских и серверных SDK могут быть автоматически сгенерированы из SwaggerHub, и существует множество дополнительных функций, которые можно использовать при разработке, тестировании и публикации своего API.
Для начала работы в SwaggerHub, надо перейти на сайт swaggerhub.com, а затем создать учетную запись или войдите в систему, используя свои учетные данные GitHub. После входа вы увидите панель инструментов (Дэшборд) SwaggerHub.
На панели инструментов отображается список созданных API. В этом примере виден API OpenWeatherMap, который используется на протяжении всего этого курса.
Редактор SwaggerHub
SwaggerHub содержит тот же редактор Swagger, к которому можно получить доступ онлайн. Этот редактор предоставляет проверку в реальном времени, при работе над спецификацией API. Однако, в отличие от отдельного редактора Swagger, в Swagger Editor SwaggerHub можно переключаться между несколькими режимами:
- Скрыть навигацию;
- Скрыть редактор и навигацию;
- Скрыть UI Docs.
Самое главное в редакторе, SwaggerHub позволяет сохранять свою работу. В бесплатном редакторе Swagger контент хранится в кеше браузера, без возможности сохранения файла в облаке. Если кеш почистить, то контент исчезнет. При использовании автономного редактора Swagger, после окончания работы надо копировать содержимое из редактора Swagger в файл на своем компьютере.
С помощью SwaggerHub можно хранить документ со своей спецификацией непосредственно на серверах SwaggerHub или ссылаться на него и сохранить его во внешнем источнике, таком как GitHub.
Версии
SwaggerHub позволяет не только хранить спецификацию OpenAPI, но и сохранять различные версии спецификации. Это значит, что можно поэкспериментировать с новым контентом, добавив новую версию. Можно вернуться к любой версии, а также опубликовать или отменить публикацию любой версии.
При публикации версии, опубликованная версия становится доступной только для чтения. Если нужно внести изменения в опубликованную версию (а не создавать новую версию), можно отменить публикацию версии и внести в нее изменения.
Можно ссылаться на конкретные версии документации или использовать более общий путь ссылки, который автоматически перенаправит на последнюю версию. Вот ссылка на API OpenWeatherMap, опубликованный на SwaggerHub, который использует версию 2.5.1 документации: https://app.swaggerhub.com/apis/IdRatherBeWriting/open-weather_map_api/2.5.1/. Чтобы сделать ссылку на конкретную версию, включите номер версии в URL. Вот более общая ссылка (в которой не указан номер версии) автоматически пересылается на последнюю версию (2.5.2): https://app.swaggerhub.com/apis/IdRatherBeWriting/open-weather_map_api/.
Управление версиями полезно, при работе над спецификацией с другими членами команды. Например, предположим, что оригинальная версия была составлена инженером, а мы хотим внести существенные изменения. Вместо того, чтобы напрямую перезаписывать содержимое (или делать резервную копию автономного файла), можно создать новую версию, а затем взять на себя больше прав, чтобы пересмотреть эту версию со своими обновлениями, не опасаясь, что инженер отреагирует отрицательно на перезаписанный / потерянный файл.
При публикации Swagger документации на SwaggerHub, базовый URL-адрес Swagger (app.swaggerhub.com) остается в URL-адресе. Хотя этот базовый URL не настраивается, можно добавить логотип своей компании и визуальный брендинг по желанию.
Встроенное комментирование/обзор
Ключ к процессу рецензирования - это возможность для членов команды комментировать спецификацию, как в Google Docs и ее аннотации на полях. При работе в редакторе SwaggerHub, слева от каждой строки расположен небольшой знак +. Чтобы добавить комментарий к строке надо нажать кнопку +.
При нажатии на +, справа появляется панель комментариев, где можно оставить комментарии, и получить ответы. Пользователи могут редактировать, удалять или разрешать комментарии. Функция комментирования помогает облегчить процесс обзора таким образом, чтобы тесно интегрироваться с контентом. Панель комментариев можно сворачивать или показывать по желанию.
Немногие инструменты поддерживают встроенные аннотации, подобные этой, и было бы невозможно без базы данных хранить комментарии вместе с профилями, связанными с рецензентами. Эту функцию было бы утомительно реализовать самостоятельно, поскольку для этого потребовалась бы база данных и механизм аутентификации. Все это включено в SwaggerHub.
Авто генерация клиентского SDK
Еще одним преимуществом SwaggerHub является возможность автоматической генерации необходимого клиентского или серверного кода из спецификации. Клиентские SDK предоставляют инструменты, необходимые для выполнения запросов API на определенных языках программирования (таких как Java или Ruby).
В верхнем правом углу по нажатию на стрелку вниз можно выбрать Client или Server. Пользователи имеют доступ к созданию клиентских и серверных SDK в более чем 30 форматах.
Предположим, что пользователь реализует наш REST API в приложении Java. Пользователь может выбрать загрузку клиентского SDK Java для расширенного кода, демонстрирующего реализацию нашего API на Java. Другие варианты включают Ruby, Android, Go, CSharp, JavaScript, Python, Scala, PHP, Swift и многие другие.
Некоторые сайты API документации выглядят впечатляюще, так как демонстрируют реализации для разных языков программирования. SwaggerHub берет эти языки программирования и умножает их в десять раз, чтобы обеспечить каждый возможный вывод, который может пожелать пользователь.
На выходе получаем простой пример кода, показывающий, как вызвать конечную точку REST на выбранном языке. Вывод включает в себя целый SDK, состоящий из различных деталей реализации на этом языке. (Для получения дополнительной информации о SDK см. SDK и примеры приложений )
Предоставление кода ускоряет реализацию для разработчиков и помогает масштабировать не зависящий от языка REST API для большего числа платформ и пользователей.
Экспорт в HTML
Среди множества возможностей SwaggerHub для генерации файлов клиента и SDK есть опция экспорта HTML. Можно экспортировать спецификацию OpenAPI в виде статического HTML-файла в одном из двух стилей: HTML или HTML2.
Демо экспорта API OpenWeatherAPI можно увидеть здесь: HTML или HTML2. Оба варианта генерируют весь контент в файл index.html.
Экспорт HTML является более простым выводом, чем HTML2. Потенциально можно включить вывод HTML в другую документацию, например, так, как Cherryleaf сделал при импорте Swagger в Flare. (Возможно, придется убрать часть кода и предоставить стили для различных элементов документации, и пользователи не смогут это опробовать) О способах интеграции узнаем больше в разделе Интеграция Swagger с документацией.
Экспорт HTML2 больше предназначен для самостоятельной работы, поскольку имеет фиксированную левую боковую панель для навигации по конечным точкам и навигационным таблицам, показывающую шесть различных примеров кода:
Для обоих выводов потребовалась бы здоровая доза индивидуального стиля, чтобы их можно было использовать.
Мок-серверы
Еще одна интересная особенность SwaggerHub - возможность создавать мок-серверы API. Предположим, есть API, в котором мы не хотим, чтобы пользователи генерировали реальные запросы. (Возможно, это система заказов, где пользователи могут заказывать продукты через API, или у нас нет тестовых аккаунтов / систем). С помощью мок-сервера можно моделировать ответы, которые позволят пользователям получить представление о том, как работает ваш API.
При наличии примеров ответов в спецификации API, можно установить для своего API «auto-mock». Когда пользователь пробует запрос, SwaggerHub возвращает пример ответа из спецификации. Ответ не будет содержать пользовательских параметров, введенных пользователем в пользовательском интерфейсе, но вместо этого будет возвращать примеры ответов, закодированных в спецификации, как если бы они были возвращены с сервера.
Предоставление «auto-mock» для API решает проблему потенциального усложнения пользовательских данных, поскольку пользователи взаимодействуют со своими реальными ключами и данными API. Во многих случаях нет необходимости в том, чтобы пользователи складывали свои данные с помощью тестов и других экспериментов. В то же время также нужно смоделировать ответ API.
Имитация API может быть особенно полезна для тестирования API с бета-пользователями. Одна из причин, по которой многие люди пишут свои API с помощью спецификации, прежде чем писать какие-либо строки кода (следуя философии “spec-first development”, описанной Майклом Стоу ), заключается в том, чтобы избегать кодирования API с конечными точками и ответами, которые не нужны пользователям.
Используя подход Мок-сервера, SwaggerHub не только предоставляет документацию, но и выступает в качестве инструмента бета-тестирования, позволяющего разработать дизайн API прямо перед тем, как потратить тысячи часов на реальное кодирование. Можно включить автоматическое моделирование для разных версий API, создавая варианты и тестируя каждый из них.
Для настройки Мок-сервера в SwaggerHub, щелкнем значок плагина и выберем добавить новую интеграцию. Выбираем сервис API Auto Mocking и заполняем детали конфигурации. Убедимся, что имеем примеры для каждого из ответов конечной точки в спецификации. См. API Auto Mocking для подробной информации.
Переиспользование контента (Домены)
Еще одна особенность, доступная исключительно в SwaggerHub, - это концепция доменов. Домены - это повторно используемые фрагменты кода, которые можно использовать, чтобы избежать дублирования в спецификации.
При создании определений для запросов и ответов, можно снова и снова использовать один и тот же код. Вместо того, чтобы дублировать этот код, можно сохранить его в виде домена. При повторном использовании кода, выбирается нужный домен.
Использование домена минимизирует дублирующийся контент и позволяет быть более последовательным и эффективным. О доменах можно прочитать больше в разделе Домены.
Организации и проекты
Совместная работа SwaggerHub - это самая распространенная причина, по которой люди переходят с опен-сорс инструментов на SwaggerHub. Может быть много разных инженеров, работающих над различными API в SwaggerHub. Чтобы организовать работу, можно сгруппировать API в организации, а затем добавить участников в соответствующую организацию. Когда этот участник входит в SwaggerHub, он или она будет видеть только те организации, к которым у него есть доступ.
Такой аспект организаций и проектов может показаться несущественным, если есть только один или два API, но стоит подумать об этом, при наличии десятков API и нескольких команд. Для таких сценариев становятся важными функции организации и проекта.
Расширяем роль технического писателя с помощью API
Технические писатели позиционируются как сильные игроки в философии “spec-first development” в дизайне OpenAPI. Становясь экспертами в кодировании спецификации OpenAPI и знакомясь с надежными инструментами для совместной работы, такими как SwaggerHub, технические писатели могут руководить командами разработчиков не только посредством создания и усовершенствования документации API, но и прокладывать путь для бета-тестирования, проверки спецификаций, клиент-серверного SDK поколения и т.д.
Разработка полнофункциональной, “high-level” спецификации OpenAPI лежит в основе этих усилий. Немногие инженеры знакомы с созданием этих спецификаций, и технические писатели, которые умеют как создавать спецификацию, так и настраивать инструменты Swagger, могут выполнять критически важные роли в командах разработки API.
Хорошие инструменты не бесплатны. SwaggerHub действительно стоит денег, но это стоит того. Бесплатные инструменты часто заброшены, плохо обслуживаются, и им не хватает документации и поддержки. Используя платный инструмент от надежной компании API (той же самой компании, которая поддерживает инструменты Swagger и спонсирует спецификацию OpenAPI), можно подключиться к инфраструктуре, необходимой для масштабирования усилий по документированию API.