swag init 找不到 @Summary 是因注释未紧贴导出的 handler 函数上方且须用 // 行注释；自定义结构体需导出并显式标注；swag serve 空白因缺少 docs/docs.go 或未正确 import；swag 不支持 ShouldBindJSON 自动推导，须手动用 @Param 声明。
为什么 swag init 找不到你的 @Summary 注释？
Go 里没有运行时反射能自动提取 HTTP handler 的路由和参数，swag 这类工具必须靠解析源码注释来生成文档。它只扫描以 // @ 开头的特殊注释块，且要求这些注释紧贴在 handler 函数上方（中间不能有空行），否则直接忽略。
常见错误包括：
- 把
// @Summary写在函数内部或结构体上 - 用
/* */多行注释包裹@指令（swag只认//行注释） - handler 函数没导出（首字母小写），导致
swag解析器跳过整个函数
正确写法示例：
// @Summary 创建用户
// @Tags users
// @Accept json
// @Produce json
// @Param user body models.User true "用户信息"
// @Success 201 {object} models.User
// @Router /users [post]
func CreateUser(c *gin.Context) {
// 实现逻辑
}
如何让 swag 正确识别自定义结构体和嵌套字段？
swag 默认只能识别标准库和常见第三方类型（如 string, int, time.Time），对自定义 struct、别名类型、嵌套 map/slice 需要显式标注，否则文档里会显示 object 或直接缺失字段。
关键做法：
- 所有参与 API 输入/输出的 struct 必须是导出的（大写首字母）
- 用
// @Description和// @Example补充字段说明和示例值 - 对匿名嵌套字段，加
swagger:ignore标签跳过不需要暴露的字段 - 对
map[string]interface{}这类动态结构，建议封装为具名 struct 并标注// @Schema
例如：
type User struct {
ID uint `json:"id" example:"1"`
Name string `json:"name" example:"Alice"`
Meta map[string]string `json:"meta"` // swag 会显示为 object，不推荐
}
// 更好写法：
type UserMeta struct {
// @Description 额外元数据键值对
Data map[string]string json:"data"
}
type User struct {
ID uint json:"id" example:"1"
Name string json:"name" example:"Alice"
Meta UserMeta json:"meta"
}
如何避免 swag serve 启动后文档空白或 404？
swag serve 是一个本地开发服务器，它依赖生成的 docs/docs.go 文件——这个文件必须存在且被主程序 import，否则页面加载的是空 JSON 或直接报错 undefined。
