Documenting Play Framework using Swagger

Оригинальный источник по настройке swagger-модуля

Play Framework — это MVC веб-фреймворк для языков программирования Java и Scala от компании ранее называемой Typesafe, а нынее Lightbend.

сайт:

Play Framework

статья с Хабра:

Впечатления от работы с Play! Framework 2.1 + Java

wiki

Play (фреймворк)

записки программиста

Play Framework — все, что вы хотели о нем узнать, но почему-то боялись спросить

Swagger — это целая множество инструментов, на протяжении всего жизненного цикла разработки API, от дизайна и документации, до тестирования и развертывания.

сайт:

Swagger

статьи с Хабра:

Документирование #микросервисов

3 лучших инструмента для описания RESTful API

wiki:

OpenAPI

Swagger (software)

Отойдя от введения можем приступить к установке API документации, которая генерируется на лету.

Для демонстрации будем использовать play framework 2ой версии: Play 2

Swagger Module

Для автоматической генерации API спецификации потребуется модуль swagger-play2

Swagger UI

На оф. сайт Swagger.io предоставляет Swagger UI, который принимает Swagger спецификацию в формате json и генерирует динамический web интерфейс для изучения, экспериментов и понимания API.

Настраиваем Play

А сейчас, давайте начнем интегрировать swagger модуль. Для тестирования используется Play Framework версии 2.6.3

Добавим plugin как dependency в сборочный файл build.sbt

libraryDependencies += "io.swagger" %% "swagger-play2" % "1.6.0"
Подключаем Swagger модуль в conf/application.conf

    play.modules.enabled += "play.modules.swagger.SwaggerModule"
    api.version = "v1" // Specify the api version.

Больше настроек могут быть добавлены в conf/application.conf для автогенерации дополнительных полей в Swagger спецификации.

Документируем API

Swagger аннотации доступны в пакете io.swagger.annotations
Swagger аннотации используются для документирования API в классах Controller-ах.

Пример кода описан ниже. Добавьте следующий код в контроллер класс.

@Api(value = "Example Controller", produces = "application/json")

Для каждого метода которому нам нужно добавить документацию, мы должны определить следующию аннотацию.
Стандартный класс ответа уже предоставлен, вот он Response.class.

 @ApiOperation(value = "Get API", notes = "Get list of id & values.", response = Response.class)

Для каждого дополнительного ответа, которое API может вернуть можно добавить следующую аннотацию.

@ApiResponses({
    @ApiResponse(code = 403, message = "Invalid Authorization", response = ErrorStatus.class),
    @ApiResponse(code = 500, message = "Internal Server Error", response = ErrorStatus.class) })

Параметры в методах контроллера могут быть добавлены следующим образом:

@ApiOperation(value = "Get User", response = User.class)
public Promise<Result> getUser(
    @ApiParam(value = "User Id", name = "userId") String userId){
        User user = getUser(userId);
        return ok(user);
    }

Маршруты(Routes)

Мы можем получить доступ к автосгенерированной Swagger спецификации добавив маршрут в конфигурационный файл conf/routes

GET     /docs/swagger.json    controllers.ApiHelpController.getResources

Сейчас, мы можем достучаться до Swagger спецификации из /docs/swagger.json

Добавим Swagger UI в Play Framework

С тех пор как Swagger UI просто динамический frontend с HTML/JS, он может предоставляться напримую через Nginx или httpd.
В альтернативе, мы также можем предоставлять Swagger UI из play framework-а.
Это также решает проблему с любой CORS ошибкой которая может возникнуть когда API и Swagger UI на разных доменах.
Скопируйте дистрибутив Swagger UI в /public/swagger-ui в Ваш Play проект.

В конфиг файле маршрутов, добавьте следующие дирекции

GET     /docs/              controllers.Assets.at(path="/public/swagger-ui",file="index.html")
GET     /docs/swagger.json  controllers.ApiHelpController.getResources
GET     /docs/*file         controllers.Assets.at(path="/public/swagger-ui",file)

В случае, если Вы хотите в корне приложения / сделать перенаправление на Swagger спецификацию по умолчанию, тогда добавим этот маршрут в конфиг маршрутов:

GET           /              controllers.Default.redirect(to = "/docs/")

Обновите index.html, чтобы поменять ссылку на Swagger спецификацию.

С

var url = window.location.search.match(/url=([^&]+)/);
if (url && url.length > 1) {
    url = decodeURIComponent(url[1]);
} else {
    url = "http://petstore.swagger.io/v2/swagger.json";
}

На

var url = window.location.search.match(/url=([^&]+)/);
if (url && url.length > 1) {
    url = decodeURIComponent(url[1]);
} else {
    url = "swagger.json";
}

Исследовать API

Однажды, sbt скомпилируется и запустит playframework, перейдите на http://localhost:9000/docs/ чтобы увидеть вживую работающий Swagger UI.

Хорошо

Использование Swagger Спец, сделанно очень просто для эффективной коммуникации с API для любого того, кто собирается испоьзовать API.
Автоматическая генерация кода клиента из Swagger спецификации сделала потребление и тестирование API очень простым.

Все ещё недостаточно хорошо

Существует несколько проблем в Swagger UI.

Иногда Вам нужно перезагрузить страницу, чтобы она вновь заработала.
Если нет соединения с API сервисом, UI не может явно сказать об этом.
Префикс пути ссылки API в настоящее время не обрабатывается в Swagger UI.
Swagger спецификация генерация включает конфигурацию безопасности не корректно реализованна(не до конца).
Возможно Вам следует использовать мажорные версии Play Framework так как существует заддержка в поддержке для последних версий.

Итого

Итого Swagger Spec/UI отличный инструмент, для описания и предоставления доступа к любому API.

Видео подключения Swagger-а можно посмотреть здесь.

Подключаем Swagger модуль в Play Framework