Golang Gin文件上传接口Swagger文档添加metadata参数问题

核心实现步骤 #

• 先定义元数据结构体，用于数据绑定和生成文档示例：

type Metadata struct {
    Key1 int    `json:"key1" example:"123"`
    Key2 string `json:"key2" example:"value"`
    Name string `json:"name" example:"my-readme"`
}

• 在接口中添加swaggo注解，重点处理metadata参数：

// @Summary 上传文件及元数据
// @Description 上传文件的同时提交JSON格式的元数据
// @Tags 文件上传
// @Accept multipart/form-data
// @Produce json
// @Param file formData file true "待上传的文件"
// @Param metadata formData string true "JSON格式的元数据" SchemaExample({"key1":123,"key2":"value","name":"my-readme"})
// @Success 200 {object} map[string]interface{} "上传成功响应"
// @Router /datafile [post]
func UploadFileAndMetadata(c *gin.Context) {
    // 获取上传文件
    file, err := c.FormFile("file")
    if err != nil {
        c.JSON(http.StatusBadRequest, gin.H{"error": err.Error()})
        return
    }

    // 读取并解析元数据
    metadataStr := c.PostForm("metadata")
    var metadata Metadata
    if err := json.Unmarshal([]byte(metadataStr), &metadata); err != nil {
        c.JSON(http.StatusBadRequest, gin.H{"error": "元数据格式无效，请传入合法JSON"})
        return
    }

    // 此处编写文件存储、元数据入库等业务逻辑

    c.JSON(http.StatusOK, gin.H{
        "message":  "上传成功",
        "filename": file.Filename,
        "metadata": metadata,
    })
}

关键说明 #

• swaggo中无法直接将metadata标记为json类型，需指定为string，通过SchemaExample字段提供JSON格式的示例，让Swagger文档展示正确的参数结构
• 结构体中的example标签会被swaggo识别，在文档中生成每个字段的示例值
• 接口内先通过PostForm获取元数据字符串，再用json.Unmarshal解析到结构体，完成数据校验和绑定

最后运行swag init重新生成Swagger文档，即可在UI中看到metadata参数的输入框和示例JSON。

内容的提问来源于stack exchange，提问作者AVarf