Play 2 和 Swagger 的可选参数答案

【问题标题】：Optional params with Play 2 and SwaggerPlay 2 和 Swagger 的可选参数
【发布时间】：2014-02-18 12:42:19
【问题描述】：

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

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

我希望 q 参数是可选的。这个Option[String] 参数有一个匹配的带注释的控制器方法。在启动时，我在日志中收到了UNKOWN TYPE，而 api-docs 生成的 json 中断了 swagger-ui：

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

还有其他方法可以在 Play 2 中指定可选参数并让 Swagger 理解吗？

【问题讨论】：

标签： scala playframework-2.2 swagger swagger-play2

【解决方案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）

我也针对 Swagger 记录了 Issue 706。

【讨论】：

【解决方案3】：

或者你可以使用这个库 https://github.com/iheartradio/play-swagger

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

【讨论】：

【解决方案4】：

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

另一种解决方法是从路由中省略选项参数

GET /documents controllers.DocumentController.getDocuments()

但是在代码中抓取它：

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

并使用 Swagger 文档的 ApiImplicitParam 对其进行注释

【讨论】：