Статьи

Play Framework: Swagger UI

Январь 1, 2018

Давайте посмотрим, как интегрировать самую популярную документацию по API в Play Framework. Я говорю о Swagger. Это очень мощный инструмент для описания REST API, и Play Framework поддерживает его с помощью отдельного модуля. В этом посте я собираюсь показать пошаговую инструкцию, как настроить Play Framework с Swagger UI.

Предварительные требования для этого учебника — базовые знания о том, как работает Play Framework (build.sbt, маршруты, контроллеры, application.conf) и умение читать очень внимательно. Когда вы выполнили предварительные требования и у вас есть Play-проект, вы можете продолжить и закончить урок.

Шаг 1

Добавьте   зависимость Swagger в  build.sbt

...
libraryDependencies ++= Seq(
  jdbc,
  anorm,
  cache,
  ws,
  filters,
  "com.wordnik" %% "swagger-play2" % "1.3.11"
)
...

Теперь мы можем использовать генерацию документации API в проекте.

Шаг 2

В   файле маршрутов нам нужно указать URI, чтобы перечислить все конечные точки REST в проекте:

GET  /api-docs.json  controllers.ApiHelpController.getResources

Шаг 3

Пришло время украсить конечные точки REST соответствующими аннотациями:

@Api(value = "/lawyers", description = "Operations with account")
object LawyerController extends Controller with UserAccountForms {
 
  @ApiOperation(
    nickname = "createAccount",
    value = "Create user account",
    notes = "User Sign Up endpoint",
    httpMethod = "POST",
    response = classOf[models.swagger.BearerToken])
  @ApiResponses(Array(
    new ApiResponse(code = 201, message = "Account successfully created"),
    new ApiResponse(code = 400, message = "Email already exist"),
    new ApiResponse(code = 500, message = "DB connection error")))
  @ApiImplicitParams(Array(
    new ApiImplicitParam(value = "Account object that need to be created", required = true, dataType = "models.swagger.UserAccountInfo", paramType = "body")))
  def createAccount = Action.async {
    implicit request => {
      //Some code here. It's not important
    }
  }
 
}

Шаг № 4

Измените   файл маршрутов снова, но теперь для конкретной конечной точки:

GET         /api-docs.json/lawyers              controllers.ApiHelpController.getResource(path = "/lawyers")
POST        /lawyers                            controllers.LawyerController.createAccount

Это минимальный набор действий, который может предоставить вам информацию о вашем REST API. Но если вы хотите больше — представление JSON в пользовательском интерфейсе, вам нужно выполнить несколько дополнительных шагов. Давайте продолжим с Swagger UI.

Шаг № 5

Загрузите  Swagger UI  и поместите все эти файлы в [project_root_dir] / public / swagger

Шаг № 6

Скопируйте  index.html  в [project_root_dir] / app / views и переименуйте его в  swagger.scala.html

Шаг № 7

Добавить URL-адрес приложения по умолчанию в  application.config

swagger.api.basepath="http://localhost:9000"

Шаг № 8

Изменить  swagger.scala.html

8.1
Добавьте строку вверху файла:

@import play.api.Play.current

8.2
Обновите все местоположения до статических ресурсов. После обновления все они будут такими:

<script src='/assets/swagger/lib/backbone-min.js' type='text/javascript'></script>

8.3
Обновите фрагмент кода JavaScript, добавив туда код Play Template:

   $(function () {
      var url = window.location.search.match(/url=([^&]+)/);
      if (url && url.length > 1) {
        url = url[1];
      } else {
        url = "@{s"${current.configuration.getString("swagger.api.basepath")
            .getOrElse("http://localhost:9000")}/api-docs.json"}"
      }
...

Шаг № 9

Добавьте действие, которое будет отвечать за отображение Swagger UI:

object Application extends Controller {
 
  def swagger = Action {
    request =>
      Ok(views.html.swagger())
  }
 
}

Шаг № 10

И, наконец, добавить строку кода в  маршруты

GET  /swagger  controllers.Application.swagger

Вот и все. Теперь вы можете использовать документацию Swagger API в своем собственном интерфейсе Swagger. Я постарался сделать этот урок максимально лаконичным, чтобы уменьшить количество вопросов, которые могут вас запутать. благодаря

40
Share: