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 或直接缺失字段。
立即学习“go语言免费学习笔记（深入）”；
关键做法：
- 所有参与 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。
典型问题链：
- 忘了运行
swag init（没生成docs/目录） - 生成后没在
main.go中 import"your-project/docs" - import 路径写错，比如漏了模块名或用了相对路径
- 用
go run main.go启动但没加-tags=swag（某些配置下需要）
检查步骤：
- 确认
docs/docs.go存在且含var swaggerSpec = ... - 确认
main.go有import _ "your-module/docs"（注意下划线导入） - 启动命令用
swag serve -g main.go -o ./docs，确保-o指向已生成的目录
为什么 swag 不支持 Gin 的 c.ShouldBindJSON() 自动推导？
swag 不执行代码，也不做类型推断，它只做静态注释解析。像 c.ShouldBindJSON(&user) 这种运行时绑定，工具根本看不到 user 是什么类型，更无法展开其字段。
必须手动用 // @Param 明确声明请求体，并指向具体 struct：
// @Param user body models.User true "用户数据"
func CreateUser(c *gin.Context) {
var user models.User
if err := c.ShouldBindJSON(&user); err != nil {
c.AbortWithStatusJSON(400, err)
return
}
// ...
}如果 struct 字段多、验证规则复杂，建议配合 swag 的 // @Schema 注释或使用 swaggo/swag v1.8+ 的 @Param 嵌套支持，但依然绕不开手动标注。
真正省事的方式不是靠工具猜，而是把接口契约提前写清楚——注释即契约，改代码前先改注释，这比任何自动化都可靠。
