swag文档生成需严格遵循语法和位置规则：注释必须紧贴首字母大写的具名handler函数、无空行，且含@Summary和@Router；结构体字段须有json:"xxx" tag；全局注释如@title须置于main包文件顶部连续块中。
swag 注释不是随便写几行注释就能生成文档的，它有一套硬性语法和位置规则，漏掉 @Summary 或 @Router，接口就直接消失；结构体字段没 json: tag，字段就为空。
注释必须紧贴 handler 函数，且不能有空行
swag 只扫描「具名函数」上方连续、无空行的 // @ 注释块。写在闭包、匿名函数、func main() 里，或者中间插一行空注释，整个函数就被跳过。
-
@Summary和@Router是强制项，缺一不可；@Summary必须是注释块第一行 - 注释块内不能混用
/* */，只认//行注释 - 函数名必须首字母大写（可导出），否则 swag 当作私有函数忽略
- 示例正确写法：
// @Summary 获取用户详情
// @Description 根据 ID 查询单个用户
// @Tags users
// @Accept json
// @Produce json
// @Param id path int true "用户ID"
// @Success 200 {object} models.User
// @Failure 404 {object} models.ErrorResponse
// @Router /api/v1/users/{id} [get]
func GetUser(c *gin.Context) {
// ...
}
@Param 类型必须和参数实际来源一致
Gin 不会把 query 参数自动映射成 path，swag 也不会猜——你写错 path 却传的是 query，文档里参数就挂错位置，前端“Try it out”填了也调不通。
-
path：对应 URL 路径变量，如/users/{id}中的id，类型写int或string（按 handler 里c.Param("id")实际转的类型） -
query：对应 URL 查询参数，如?page=1&limit=10，类型写int、string等原始类型 -
body：仅用于 POST/PUT，必须配@Success 200 {object} YourStruct，且结构体字段要有json:tag - 别写
@Param data body interface{}——swag 解析不出字段，响应模型会是空{}
结构体字段不显示？大概率缺 json: tag 或未导出
swag 不反射字段，也不读字段名，它只认 json: tag 的键名。字段名是 UserName，但 tag 是 json:"user_name"，文档里就显示 user_name；没 tag 就不出现，哪怕字段是导出的。
立即学习“go语言免费学习笔记（深入）”；
- 所有要出现在文档里的字段，都得是首字母大写 +
json:"xxx" -
time.Time字段建议加time_format:"2006-01-02T15:04:05Z"，否则可能渲染成 Unix 时间戳数字 - 嵌套结构体（如
User.Address *Address）要求Address类型本身也有json:tag，且被当前文件 import - 别用
map[string]interface{}或interface{}作响应体——改用明确结构体，或struct{ Data interface{} }+@Schema注释说明
swag init 找不到 @title？检查注释位置和模块路径
报错 failed to parse general API info，90% 是因为 // @title 这类全局注释没写对地方：它必须在 main 包的某个 .go 文件顶部，且连续无空行，也不能被其他代码或注释隔开。
- 如果项目结构是
cmd/myapp/main.go，执行swag init -g cmd/myapp/main.go，别只在根目录跑默认命令 - 确保
main.go在package main下，且// @title块前面没有其他 Go 代码（包括import） - 跨 module 引用结构体（如
models.User）时，必须加// @modelsPackage github.com/yourname/project/models - 字段用
snake_case（如user_name string `json:"user_name"`）时，加-p snakecase参数，否则字段名解析失败
最常被忽略的一点：注释写对了，swag init 也成功了，但文档里还是没接口——八成是 handler 函数没被 main.go 或其 import 链路覆盖到，或者路由注册用的是闭包而非具名函数。swag 不运行代码，它只看注释和 AST，别指望它“猜”逻辑。
