Scala Play框架下Swagger POST请求Body丢失问题排查

问题根源分析 #

你遇到的问题来自两个核心错误：

1. Swagger路由注释配置错误：原注释用过时的parameters方式声明请求体，且错误将schema定义为string，导致Swagger UI无法识别正确的请求结构，不会生成Payload输入区域，发送请求时自然没有携带数据。
2. 控制器请求处理不匹配：默认Action处理AnyContent类型，你使用的表单绑定bindFromRequest()仅适配表单编码请求，而Swagger默认发送JSON格式请求，两者不匹配导致绑定失败，调用.get时直接抛出异常。

分步修复方案 #

1. 修正Swagger路由注释 #

Play框架的Swagger插件支持OpenAPI 3.0规范，需用requestBody定义请求体，并正确描述UserRegistration的结构。修改后的routes注释如下：

###
#   summary: 提交用户注册信息
#   requestBody:
#     required: true
#     content:
#       application/json:
#         schema:
#           type: object
#           required:
#             - name
#             - email
#             - hash
#           properties:
#             name:
#               type: string
#             email:
#               type: string
#               format: email
#             hash:
#               type: string
#   tags:
#       - users
#   responses:
#       '200':
#         description: 请求成功，返回提交的用户信息
#         content:
#            application/json:
#              schema:
#                type: object
#                properties:
#                  name:
#                    type: string
#                  email:
#                    type: string
#                    format: email
#                  hash:
#                    type: string
###
+nocsrf
POST     /api/users                  controllers.UserController.postExample()

如果你的项目已配置Swagger自动扫描模型（比如用play-swagger插件并给模型加了@ApiModel注解），也可以用$ref简化配置：

# ...
schema:
  $ref: '#/components/schemas/UserRegistration'
# ...

2. 调整控制器的请求解析逻辑 #

因为Swagger发送的是JSON请求，需改用JSON解析器处理请求体，避免表单绑定的兼容性问题。

首先确保UserRegistration模型定义了JSON格式支持（在models/UserRegistration.scala中）：

import play.api.libs.json._
import play.api.data.Form
import play.api.data.Forms._

case class UserRegistration(name: String, email: String, hash: String)

object UserRegistration {
  // JSON序列化/反序列化格式
  implicit val jsonFormat: OFormat[UserRegistration] = Json.format[UserRegistration]
  
  // 表单绑定（如需支持表单提交可保留）
  val form = Form(
    mapping(
      "name" -> nonEmptyText,
      "email" -> email,
      "hash" -> nonEmptyText
    )(UserRegistration.apply)(UserRegistration.unapply)
  )
}

然后修改控制器的postExample方法：

def postExample = Action(parse.json) { implicit request =>
  // 验证并解析JSON请求体
  request.body.validate[UserRegistration].fold(
    // 解析失败返回错误信息
    errors => BadRequest(Json.obj("error" -> JsError.toJson(errors))),
    // 解析成功返回用户信息
    user => Ok(Json.toJson(user))
  )
}

如果需要同时支持表单和JSON两种提交方式，可改用parse.anyContent分支处理：

def postExample = Action(parse.anyContent) { implicit request =>
  val parseResult = request.body.asJson match {
    case Some(json) => json.validate[UserRegistration].map(Right(_))
    case None => UserRegistration.form.bindFromRequest().fold(
      formErrors => Left(formErrors),
      user => Right(user)
    )
  }

  parseResult match {
    case Right(user) => Ok(Json.toJson(user))
    case Left(formErrors) => BadRequest(Json.obj("errors" -> formErrors.errors.map(_.message)))
    case JsError(errors) => BadRequest(Json.obj("errors" -> JsError.toJson(errors)))
  }
}

3. 验证修复效果 #

重启Play应用后，打开Swagger UI查看POST /api/users接口：

• 会显示完整的请求体输入表单（包含name、email、hash三个字段）
• 发送请求时，Swagger自动生成正确的JSON Payload
• 控制器可正常解析请求体，不再抛出NPE

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