英文:
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 loginUserRequestif 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 loginUserRequestif err := ctx.ShouldBindJSON(&req); err != nil {ctx.JSON(http.StatusBadRequest, utils.ErrorResponse(err))return}// some codectx.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.
通过集体智慧和协作来改善编程学习和解决问题的方式。致力于成为全球开发者共同参与的知识库，让每个人都能够通过互相帮助和分享经验来进步。
评论