21.12.2017 11:37
isatimur 0 485 Источник
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


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


    libraryDependencies += "io.swagger" %% "swagger-play2" % "1.6.0"


  2. Подключаем 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-а можно посмотреть здесь.

Комментарии (0)