Question

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

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

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

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

是否有另一种方法可以在Play 2中指定可选参数并让Swagger理解它？

Answer 1

到目前为止，我发现的一个解决方法是从params列表中删除param，使用Swagger的@ApiImplicitParams注释并从控制器方法中的请求对象中获取param。然后，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文档。

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记录了Issue 706。

Answer 3

您使用的是什么版本的招摇？这应该得到支持。

Answer 4

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

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

Answer 5

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为Swagger文档注释它

Play 2和Swagger的可选参数

5 个答案: