Optional params with Play 2 and Swagger

Question

I'm trying to use Swagger to document a Play 2 REST API but swagger-play2 doesn't seem to understand optional parameters defined with Scala's Option type - the normal way to make a param optional in Play 2:

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

I want the q param to be optional. There is a matching annotated controller method with this Option[String] param. On startup I'm getting UNKOWN TYPE in the log and the json produced by api-docs breaks swagger-ui:

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

Is there another way to specify an optional parameter in Play 2 and have Swagger understand it?

Answer 1

One workaround I've found so far is to remove the param from the params list, use Swagger's @ApiImplicitParams annotation and grab the param from the request object in your controller method. Swagger will then consider the param to be optional.

GET /documents controllers.DocumentController.getDocuments()

and then in the controller:

@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
}

This is certainly not as nice as using Scala's Option type but it produces correct Swagger docs.