Swagger如何描述JSON主体参数

Question

我正在尝试向我的 Rest API（Gin 框架）添加文档，并且在尝试构建 JSON 主体参数时遇到了一些问题。

目前我有以下API描述操作：

// @Summary logins a user
// @ID      login-user
// @Accept  json
// @Produce json
// @Param   email       formData string true "user email"
// @Param   password    formData string true "user password"
// @Success 200 {object} gin.H  "login response"
// @Failure 400 {object} gin.H  "error response"
// @Router  /login [post]
func (server *Server) handleLoginUser() gin.HandlerFunc {
    return func(ctx *gin.Context) {
        var req loginUserRequest
        if err := ctx.ShouldBindJSON(&req); err != nil {
            ctx.JSON(http.StatusBadRequest, utils.ErrorResponse(err))
            return
        }

        // some code

        ctx.JSON(http.StatusOK, response)
    }
}

当我通过 Swagger UI 提交数据时，出现以下错误：

{
"error": "invalid character 'e' looking for beginning of value"
}

另外，这是生成的 cURL：

curl -X 'POST' \
  'http://localhost:8080/api/login' \
  -H 'accept: application/json' \
  -H 'Content-Type: application/json' \
  -d 'email=my%40email.com&password=password'

值得一提的是，每当我在 Postman 中使用 body Raw JSON 提交相同的数据时，它都会起作用。这就是通常的 JSON 的样子（也loginUserRequest）：

curl -X 'POST' \
  'http://localhost:8080/api/login' \
  -H 'accept: application/json' \
  -H 'Content-Type: application/json' \
  -d 'email=my%40email.com&password=password'

由于我是 Swagger 的新手，我很确定它与Swagger 的 [属性文档] 上定义的email&相关。password param type

那么，我应该如何更好地描述loginRequestJSON 主体呢？

Answer 1

这很简单，但我猜他们在文档中省略了这一点。我刚刚更改了参数如下：

// @Param   loginUserRequest body loginUserRequest true "user password"

然后，运行时swag init --parseDependency --parseInternal --parseDepth 1它就起作用了。