json - 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):

{
   "email": "<a href="https://stackoverflow.com/cdn-cgi/l/email-protection" class="__cf_email__" data-cfemail="d5b8ac95b8b4bcb9fbb6bab8" rel="noreferrer noopener nofollow">[email protected]</a>",
   "password": "password"
}

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

那么，我应该如何更好地描述 loginRequest JSON 正文？

Answer 1

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

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

然后，当运行 swag init --parseDependency --parseInternal --parseDepth 1 时，它就可以工作了。