英文:
Swagger How to describe JSON body parameter
问题
我正在尝试为我的 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
}
// 一些代码
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 中使用原始 JSON 请求体提交相同的数据时，它可以正常工作。这是一个典型的 JSON 示例（也是 loginUserRequest）：
{
"email": "my@mail.com",
"password": "password"
}
由于我对 Swagger 还不熟悉，我相信问题与 Swagger 的 [attribute documentation] 中定义的 email 和 password 参数类型有关。
那么，我应该如何更好地描述 loginRequest 的 JSON 请求体呢？
英文:
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": "my@mail.com",
"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?
答案1
得分: 5
这很容易，但我猜他们在文档中省略了这一部分。我只是按照以下方式更改了参数：
// @Param loginUserRequest body loginUserRequest true "user password"
然后，在运行 swag init --parseDependency --parseInternal --parseDepth 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.
通过集体智慧和协作来改善编程学习和解决问题的方式。致力于成为全球开发者共同参与的知识库，让每个人都能够通过互相帮助和分享经验来进步。
评论