15

我正在尝试使用 Swagger 记录 Play 2 REST API，但swagger-play2似乎不理解使用 ScalaOption类型定义的可选参数 - 在 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 理解它？

4

4 回答 4

1

我已经解决了这个问题，类似于@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 。

于 2014-09-30T03:29:42.293 回答
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 文档。

于 2014-02-21T17:24:46.047 回答
0

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

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

于 2015-09-28T14:46:24.960 回答
0

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 对其进行注释

于 2016-03-22T14:07:10.300 回答