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

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

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

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

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

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


swagger scala playframework-2.2 swagger-play2
person Tom Wadley    schedule 18.02.2014    source источник

Ответы (4)


arrow_upward
1
arrow_downward

Одно временное решение, которое я нашел до сих пор, - это удалить параметр из списка параметров, использовать аннотацию Swagger @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.

person Tom Wadley    schedule 21.02.2014

arrow_upward
1
arrow_downward

Я работал над этим аналогично ответу @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.

person Michael Iles    schedule 30.09.2014

arrow_upward
0
arrow_downward

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

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

person KailuoWang    schedule 28.09.2015

arrow_upward
0
arrow_downward

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

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

GET /documents controllers.DocumentController.getDocuments()

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

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

и аннотируйте его с помощью ApiImplicitParam for Swagger docs

person galbarm    schedule 22.03.2016