使用Play 2和Swagger的可选参数

Question

我正在尝试使用Swagger来记录Play 2 REST API，但是 swagger-play2 似乎不理解使用Scala的 Option 类型定义的可选参数 - 这是在Play 2中使参数可选的常规方式：

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

我希望q参数是可选的。有一个匹配的注释控制器方法，带有此Option[String]参数。启动时，在日志中出现UNKNOWN TYPE，并且由api-docs生成的JSON会破坏swagger-ui：

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

在 Play 2 中有没有其他指定可选参数的方式，并让 Swagger 能够理解它？

- Tom Wadley

Answer 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文档。

- Tom Wadley

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）

我也在Swagger中记录了问题706。

- Michael Iles

Answer 3

APIImplicitParam 的解决方法对我不起作用。

另一个解决方法是从路由中省略 option 参数。

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文档进行注释

- galbarm

Answer 4

另外，您可以使用此库https://github.com/iheartradio/play-swagger

这个库采用了一种不同的方法，不需要注解（强制你学习新的API），你可以直接在路由文件中编写swagger规范作为注释。它会根据路由文件自动生成参数定义，并且对于类型为Option[T]的参数，它会自动将其标记为required=false。

- KailuoWang