Необязательные параметры с Play 2 и Swagger

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

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

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

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

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

Ответы

Ответ 1

Обходным решением, которое я нашел до сих пор, является удаление параметра из списка параметров, использование аннотации 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
}

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

Ответ 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)

Я зарегистрировал Issue 706 против Swagger тоже.

Ответ 3

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

Ответ 4

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

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

Ответ 5

Обходной путь 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