Дополнительные параметры с Play 2 и Swagger

Question

Я пытаюсь использовать Swagger для документирования API Play 2 REST, но swagger-play2 кажется, не понимают необязательные параметры, определенные с помощью Scala Option type - обычный способ сделать необязательный параметр в Play 2:

GET /documents controllers.DocumentController.getDocuments(q: Option[String])

Я хочу q параметр должен быть необязательным. Существует соответствующий метод аннотированного контроллера с этим Option[String] пары. При запуске я получаю UNKOWN TYPE в журнале и JSON, созданный перерывы API-документы swagger-ui:

UNKNOWN TYPE: scala.Option
[info] play - Application started (Dev)

Есть ли другой способ указать необязательный параметр в Play 2, и Swagger понимает это?

Answer 1

Один обходной путь, который я нашел до сих пор, состоит в том, чтобы удалить параметр из списка параметров, используя Swagger's. @ApiImplicitParams аннотации и захватить параметр из объекта запроса в вашем методе контроллера. Swagger будет считать параметр необязательным.

GET /documents controllers.DocumentController.getDocuments()

а затем в контроллере:

@ApiOperation(...)
@ApiImplicitParams(Array(
  new ApiImplicitParam(name = "q", value = "Query", required = false, dataType = "string", paramType = "query"),
))
def getDocuments = Action { implicit request => 
  // use param via request object
}

Это, конечно, не так хорошо, как использование типа Option в Scala, но дает правильные документы Swagger.

Answer 2

Я работал над этим аналогично ответу @Tom Wadley.

Этот код создает проблему:

@ApiOperation( ... )
def foo(@ApiParam(value="Argument 1") @PathParam("a1") a1 : Option[Int]) = ...

Чтобы избежать этой проблемы, просто удалите аннотации из аргумента и вместо этого объявите неявный параметр с тем же именем:

@ApiOperation( ... )
@ApiImplicitParams(Array(new ApiImplicitParam(name="a1", dataType="Int", required=false, paramType="query", ...)
def foo(a1 : Option[Int]) = ...

(Scala 2.11.2, Play 2.3, Swagger 1.3.8)

Я зарегистрировал Выпуск 706 против Swagger тоже.

Answer 3

Какую версию Swagger вы используете? Это должно быть поддержано.

Answer 4

Обходной путь APIImplicitParam не работал для меня.

Другой обходной путь - опустить параметр param из маршрутов.

GET /documents controllers.DocumentController.getDocuments()

Но возьмите это в коде:

val qSeq = request.queryString.get("q")
val q = qSeq match {
  case None => None
  case Some(seq) => seq.headOption
}

и аннотировать его с помощью ApiImplicitParam для документов Swagger

Answer 5

В качестве альтернативы вы можете использовать эту библиотеку https://github.com/iheartradio/play-swagger

Эта библиотека использует иной подход, чем аннотация (которая заставляет вас изучать новый API), вы записываете спецификации swagger непосредственно в файл маршрутов в виде комментариев. Он автоматически генерирует определение параметров на основе файла маршрутов и для параметров, введенных в Option[T], автоматически помечает их как обязательные =false.