Визуализация и тестирование REST API с помощью Swagger на WebSphere Liberty

В последние годы все большую популярность набирает стандарт описания интерфейсов RESTful веб-сервисов Swagger. Фактически Swagger становится для RESTful-сервисов тем же, чем является WSDL для SOAP-сервисов. При этом разработчики серверов приложений активно добавляют поддержку данного стандарта в свои продукты. Вот и флагманский сервер приложений WebSphere Liberty корпорации IBM обзавелся новой возможностью apiDiscovery, позволяющей найти все доступные на сервере REST API и динамически создать Swagger-подобный интерфейс пользователя для тестирования найденных конечных точек.

В данной статье мы рассмотрим процесс реализации некоего REST API с помощью сервлетов, его документирования на Swagger и тестирования с помощью пользовательского интерфейса apiDiscovery. Дополнительно я расскажу о достаточно богатом механизме обнаружения сервером приложений доступных Swagger-документов и генерации таковых по аннотациям JAX-RS и Swagger.

Пример использования apiDiscovery

Предположим, что есть некий интернет магазин книг, административная часть которого представлена в виде REST API. В состав данного API входит и метод регистрации новой книги для продажи. Данный метод принимает на вход isbn-код книги и ее описание в формате JSON (как минимум - данные об авторе и название). Так как речь идет о добавлении новой сущности, то разумно использовать HTTP-метод POST. Реализовать логику добавления книги удобно в качестве обработчика метода POST сервлета, т.е. внутри метода doPost(HttpServletRequest request, HttpServletResponse response). Для работы с поточными данными в формате JSON будем использовать JSR 353, являющийся частью Java EE 7 и предоставляющий API для разбора, трансформации и построения запросов к данным в формате JSON как в объектном, так и в поточном режиме.



Чтобы данный сервлет стал доступен для тестирования с использованием apiDiscovery, предоставляемую им функциональность необходимо описать в формате Swagger и поместить в файл META-INF/swagger.json или META-INF/swagger.yaml веб-модуля.



Теперь apiDiscovery сможет динамически создать пользовательский интерфейс для проверки функциональности сервлета. Интерфейс будет доступен по адресу https://host:https-port/ibm/api/explorer/. Данный путь находится в защищенной зоне сервера приложений, для доступа к нему в файле конфигурации server.xml необходимо настроить реестр пользователей, например basicRegistry:



Если сервер приложений настроен корректно, то при обращении к API Explorer'у станет доступна форма тестирования метода API, на которой можно заполнить все необходимые параметры и проверить работоспособность сервиса.

Ответ сервиса интерпретируется API Explorer'ом, из него извлекаются тело и заголовки, которые добавляются в соответствующие поля формы.

Обнаружение доступных описаний REST API

Возможность apiDiscovery поддерживает несколько механизмов поиска и создания документов в формате Swagger для описания предоставляемого сервером или развернутыми приложениями REST API.

SPI com.ibm.wsspi.rest.api.discovery.APIProvider

Возможность apiDiscovery использует метод getDocument интерфейса SPI com.ibm.wsspi.rest.api.discovery.APIProvider. Данный метод позволяет бандлам OSGi из расширенных возможностей добавлять что-либо к "мастер" документации. В последних релизах WebSphere Liberty поддерживаются только форматы JSON и YAML.

Использование содержимого развернутого веб-приложения

Каждый веб-модуль может добавить к набору Swagger-документации один свой документ. Несколько WAR-файлов, инкапсулированных в EAR-приложение, могут публиковать различные документы, удовлетворяющие стандарту Swagger 2.0. Самый простой способ опубликовать документацию по предоставляемому модулем API - включить файл swagger.json или swagger.yaml в соответствующий каталог META-INF. Во время развертывания приложения возможность apiDiscovery осуществляет поиск файла META-INF/swagger.json внутри каждого веб-модуля. Если таковой файл не найден, то осуществляется поиск файла META-INF/swagger.yaml.

Другой вариант выставить документацию по REST API, предоставляемому веб-модулем, - указать путь к файлам swagger.json/swagger.yaml явно в конфигурационном файле server.xml. Для этого необходимо поместить в данный файл элемент webModuleDoc для каждого веб-модуля, перечислив данные элементы внутри родительского тега apiDiscovery. Например так:



Элемент webModuleDoc должен содержать атрибут contextRoot, позволяющий однозначно идентифицировать веб-модуль, путь к документации для которого нужно настроить. Опциональный атрибут enabled позволяет включать и отключать обнаружение API для конкретного веб-модуля. По-умолчанию значение данного атрибута равно true. Атрибут docURL определяет место размещения документации для модуля, если задан путь, начинающийся со знака слэш (/), то путь отсчитывается относительно корневого контекста веб-приложения, если же URL начинается с префикса http:// или https://, то он представляет собой абсолютный путь к документу.

Обработка аннотаций JAX-RS и Swagger

Если веб-приложение выставляет REST-сервисы, используя соответствующие аннотации JAX-RS, и при этом не предоставляет документов swagger.json или swagger.yaml (очень важное требование!), то сервер приложений WebSphere Liberty может автоматически сгенерировать данные документы. Для этого в конфигурацию сервера должны быть добавлены возможности apiDiscovery-1.0 и jaxrs-1.1 или jaxrs-2.0. Пример конфигурации:



Сервер приложений сканирует все классы внутри веб-модулей с целью обнаружения JAX-RS и Swagger аннотаций (@Path, @Api и @SwaggerDefinition). Сгенерированная документация будет доступна по следующим адресам: http://host:port/context-root/swagger.json и http://host:port/context-root/swagger.yaml.

Для примера рассмотрим следующий ресурс JAX-RS:



После обработки аннотаций сервером приложений будет создан документ swagger.json (см. соответствующий Gist) и API Explorer сможет показать для него форму проверки работоспособности.

Слияние заданной явно документации и сгенерированной по аннотациям

Можно использовать возможность apiDiscovery-1.0 для слияния ранее созданной документации с документацией, генерируемой при обработке найденных в составе приложения аннотаций. Сервер приложений осуществляет поиск файла META-INF/stub/swagger.json или META-INF/stub/swagger.yaml внутри веб-модуля. Если один из данных файлов присутствует, то будет сгенерирован Swagger-документ, комбинирующий содержимое данного файла и результат обработки найденных в результате сканирования классов модуля аннотаций JAX-RS и Swagger. Файл будет доступен по следующим адресам: http://host:port/context-root/swagger.json и http://host:port/context-root/swagger.yaml.

Данный механизм удобно использовать для документирования API, реализованного с помощью сервлетов, не являющихся ресурсами JAX-RS, поскольку такая документация будет автоматически объединена с документацией по JAX-RS частям вашего API.

Выводы

Богатые REST API все более повсеместно приходят в нашу жизнь. Несколько лет назад Суровый публиковал заметку SOAP vs RESTful, в которой делал вывод, что основным преимуществом SOAP является наличие строгих стандартов, в том числе и стандарта описания интерфейса сервиса. При использовании REST не всегда понятно что именно скрывается за термином "примените вот этот HTTP-метод к такому-то ресурсу". Swagger, ставший в последнее время стандартом де-факто для описания RESTful-интерфейсов, смог существенным образом изменить картину, предоставив возможность создания документов, читаемых как человеком, так и множеством имеющихся в наличие инструментальных средств. Отрадно также, что компания IBM и в данной области находится на острие прогресса, внедрив поддержку данного стандарта как в свой флагманский сервер приложений, так и в сервисную шину предприятия IBM Integration Bus.

Понравилось сообщение - подпишитесь на блог