Swagger How to describe JSON body parameter

Question

I am trying to add documentation to my Rest API (Gin framework) and I stepped in some problems while trying to structure a JSON body parameter.

Currently, I have the following API description operations:

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

When I submit the data through Swagger UI I get the following error:

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

Also, this is the generated 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'

It's worth to mention that whenever I submit the same data in Postman with body Raw JSON it works. This is what a usual JSON looks like (also, loginUserRequest):

{
   "email": "[email protected]",
   "password": "password"
}

Since I am new to Swagger, I am pretty sure it's something related to the email & password param type defined on the Swagger's [attribute documentation].

So, how should I describe better the loginRequest JSON body?

Answer 1

It was pretty easy, but I guess they omitted that in the documentation. I just changed the parameter as following:

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

And then, when running swag init --parseDependency --parseInternal --parseDepth 1 it works.