Scala Play Framework集成Swagger多查询参数适配问题咨询

核心问题原因 #

sbt-play-swagger默认关闭了case class类型查询参数的自动展开能力，因此会将整个case class参数识别为单个字符串输入项。

解决步骤 #

• 第一步：在build.sbt的settings配置块中添加自动展开配置
  在你现有build.sbt的settings块内新增如下配置即可开启自动展开：

  swaggerExpandCaseClassParams := true
  

• 第二步：确认CarsSearch类的存放路径
  你当前配置的swaggerDomainNameSpaces := Seq("application.models")，请确保CarsSearch case class定义在application.models包或其子包下，否则swagger无法扫描到类的字段结构。
• 第三步（可选）：为字段补充元信息注解
  可以给CarsSearch的字段添加@ApiParam注解，明确参数含义、是否必填、示例值等信息，示例如下：

  import io.swagger.annotations.ApiParam
  
  case class CarsSearch(
    @ApiParam(value = "车辆品牌", required = false, example = "丰田")
    brand: Option[String],
    @ApiParam(value = "最低售价(单位：元)", required = false, example = "100000")
    priceMin: Option[Int],
    @ApiParam(value = "最高售价(单位：元)", required = false, example = "300000")
    priceMax: Option[Int]
  )
  

• 第四步（备选：自动展开失效时使用）：在routes文件手动声明参数
  如果开启自动展开后仍不生效，可以在routes文件对应接口上方手动声明所有查询参数：

  ###
  # @summary 车辆搜索接口
  # @param [in] brand 车辆品牌 可选
  # @param [in] priceMin 最低售价 可选
  # @param [in] priceMax 最高售价 可选
  ###
  GET   /api/cars    controllers.CarController.searchCars(carsSearch: CarsSearch)
  

效果对比 #

• 当前异常效果：
  
• 预期实现效果：
  

内容的提问来源于stack exchange，提问作者Bartek