在 Golang 中如何使用 Swag 处理 JSON 请求参数？

在 Golang 中使用 Swag 处理 JSON 请求参数需结合 Swag 注解 和 Go 代码解析，以下是具体实现步骤：

1. Swag 注解配置

在代码注释中使用 @param 注解描述 JSON 请求体，关键参数说明：

body：指定参数为请求体（JSON 格式）。
结构体描述：若参数为复杂对象，需通过结构体字段注解详细说明。

示例 1：简单 JSON 请求体// @Summary 示例接口// @Description 接收简单 JSON 请求// @Accept json// @Produce json// @Param request body string true "请求体 (JSON)"// @Success 200 {string} string "成功响应"// @Router /api/example [post]func SimpleHandler(w http.ResponseWriter, r *http.Request) { // 处理逻辑...}示例 2：复杂 JSON 结构体

定义结构体并添加字段注解（需在文件顶部声明结构体）：

// User 请求结构体type User struct { Name string `json:"name" example:"张三"` Age int `json:"age" example:"25"`}// @Summary 用户创建接口// @Description 接收用户信息// @Accept json// @Produce json// @Param user body User true "用户信息"// @Success 200 {object} User "创建成功"// @Router /api/user [post]func UserHandler(w http.ResponseWriter, r *http.Request) { // 处理逻辑...}2. Go 代码解析 JSON 请求体

使用 encoding/json 包解析请求体，步骤如下：

读取请求体：通过 io.ReadAll 获取原始数据。
反序列化：使用 json.Unmarshal 将 JSON 转为 Go 结构体。
错误处理：检查读取和解析错误。

完整示例import ( "encoding/json" "io" "net/http")type RequestData struct { Name string `json:"name"` Age int `json:"age"`}func MyHandler(w http.ResponseWriter, r *http.Request) { // 1. 读取请求体 body, err := io.ReadAll(r.Body) if err != nil { http.Error(w, "读取请求体失败", http.StatusBadRequest) return } defer r.Body.Close() // 必须关闭 // 2. 解析 JSON 到结构体 var data RequestData err = json.Unmarshal(body, &data) if err != nil { http.Error(w, "JSON 解析失败", http.StatusBadRequest) return } // 3. 使用解析后的数据 w.Write([]byte(fmt.Sprintf("Hello, %s! Age: %d", data.Name, data.Age)))}3. 关键注意事项

结构体标签：确保 json:"field" 标签与 JSON 字段名一致。
错误处理：始终检查 io.ReadAll 和 json.Unmarshal 的错误。
请求体关闭：使用 defer r.Body.Close() 避免资源泄漏。
Swag 注解位置：将注解放在处理函数上方，确保 swag init 能正确生成文档。

4. 生成 API 文档

安装 Swag：go install github.com/swaggo/swag/cmd/swag@latest
在项目根目录运行：swag init
生成的文档位于 docs/ 目录，可通过 Swagger UI 访问（需集成 swaggo/http-swagger）。

5. 常见问题解决

问题 1：Swag 生成的文档未显示 JSON 参数。解决：检查 @Param 注解是否包含 body 类型和正确的结构体名称。
问题 2：JSON 解析失败。解决：验证请求头 Content-Type: application/json，并确保结构体字段与 JSON 匹配。
问题 3：结构体字段未映射。解决：检查 json 标签是否拼写正确（如 json:"name" 而非 json=name）。

通过以上步骤，可实现 Swag 注解自动生成文档 + Go 代码正确解析 JSON，确保 API 开发高效且文档清晰。

您可能感兴趣问答

Collapsible

热门标签

热点问答