Swagger文档生成问题：如何将CreateDatabaseRequest结构体正确标记为请求体参数而非查询参数

我之前也踩过这个坑，gin-swagger的参数解析逻辑确实有容易混淆的地方。完全不需要额外创建虚拟结构体，只要调整原结构体和接口的Swagger注释就能搞定，具体做法如下：

步骤1：修正请求体结构体的Swagger注释 #

给CreateDatabaseRequest加上swagger:model标签，让它被Swagger识别为一个独立的请求体模型，而不是零散的参数集合：

// CreateDatabaseRequest 数据库创建请求体
// swagger:model
type CreateDatabaseRequest struct {
    // 数据库名称
    // required: true
    Name string `json:"name" binding:"required"`
    // 关联的分组ID
    // required: true
    GroupId uint `json:"groupId" binding:"required"`
}

这里的swagger:model会告诉gin-swagger把这个结构体注册为Swagger定义中的一个模型，后续可以直接引用它。

步骤2：在接口的Swagger注释中显式指定请求体 #

接下来修改你的接口路由注释，在Parameters部分明确声明body参数，并通过$ref关联到上面定义的模型：

// 创建数据库
// swagger:route POST /databases createDatabase
//
// 创建一个新的数据库实例
//
// Security:
// oauth2:
//
// Parameters:
// + name: body
//   in: body
//   description: 数据库创建的详细参数
//   required: true
//   schema:
//     "$ref": "#/definitions/CreateDatabaseRequest"
//
// responses:
// 202: Database
// 401: Error
// ...
func (h Handler) Create(c *gin.Context) {
    var request CreateDatabaseRequest
    if err := handler.DataBinder(c, &request); err != nil {
        _ = c.Error(err)
        return
    }
    // ... 其他业务逻辑
}

为什么原来的方式会出错？ #

你之前直接在结构体上标注swagger:parameters createDatabase和in: body，gin-swagger会把这种写法解析为将结构体的每个字段拆分为独立的参数，而不是把整个结构体作为一个完整的请求体。通过上面的方式，我们明确告诉Swagger：这是一个body参数，它的结构对应我们定义的CreateDatabaseRequest模型，这样就不会被误识别为查询参数了。

这样修改后重新生成Swagger文档，你就能看到完整的请求体结构展示，而不是两个独立的查询参数了。

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