使用swag生成Go API文档前必须添加@Summary和@Success注释，否则接口描述显示“undefined”、响应结构消失；@Summary需紧贴函数且单行，@Success中结构体须导出并带json tag，字段无tag则不显示，嵌套结构需逐层标注，time.Time建议显式指定time_format，路由文件需通过-d指定扫描目录，请求体参数须用@Param body声明。
用 swag 生成 Go API 文档前必须加 @Summary 和 @Success
swag 不是靠反射自动提取函数返回值类型，而是依赖注释解析。没写 @Summary，生成的接口会显示 “undefined”；没写 @Success，响应结构在文档里直接消失，连状态码都不显示。
常见错误现象：运行 swag init 后打开文档，所有接口描述为空、响应体显示 “object”，点开全是空 schema。
-
@Summary必须紧跟在函数上方，不能隔行，且只能有一行文本 -
@Success 200 {object} model.UserResponse中的model.UserResponse必须是已导出（首字母大写）且有 JSON tag 的 struct - 如果返回的是指针（如
*UserResponse），注释里仍写{object} model.UserResponse，swag 不识别指针符号
struct 字段不加 json: tag 就不会出现在文档响应体中
swag 解析 struct 时只看 json tag，不是看字段是否导出。哪怕字段名是 UserName 且首字母大写，只要没写 json:"user_name"，它就不会被加入 OpenAPI schema。
使用场景：你定义了 type User struct { ID int; Name string }，但生成文档时 response 里只有 id（因为 ID 默认映射为 id），Name 却消失了——大概率是漏了 json:"name"。
立即学习“go语言免费学习笔记（深入）”；
- 嵌套 struct 也要逐层加 tag，否则深层字段不出现
- 忽略字段用
json:"-"，swag 会跳过该字段 - 字段类型为
time.Time时，建议显式写json:"created_at" time_format:"2006-01-02T15:04:05Z"，否则文档里可能显示为 float64 时间戳
swag init 扫描不到 main.go 外的路由注册文件
默认情况下，swag init 只扫描当前目录及子目录下的 .go 文件，但如果你把 router := gin.Default() 和 router.GET(...) 写在 internal/router/router.go 里，而 main.go 里只做初始化调用，swag 很可能找不到这些路由声明。
原因：swag 不执行代码，只静态解析注释 + 函数签名，它需要看到 handler 函数被某个 HTTP 方法（如 GET、POST）直接绑定的地方，或至少能追踪到 handler 的定义位置。
- 确保 handler 函数上方有完整的 swag 注释（
@Router、@Param等） - 运行命令时加
-g main.go指定入口，再用-o ./docs指定输出目录 - 如果路由分散在多个文件，用
-d ./显式指定扫描根目录，避免遗漏
Gin 中用 c.ShouldBindJSON 时，@Param 要写 body 类型而非 query
很多人把请求体参数误标为 @Param query 或 header，结果文档里 body 输入框不出现，或者 swagger-ui 提交时报 400 —— 因为 swag 把它当 URL 参数处理了。
正确做法是明确声明 body 结构：
// @Param user body model.User true "用户信息"
// @Success 200 {object} model.User
func CreateUser(c *gin.Context) {
var user model.User
if err := c.ShouldBindJSON(&user); err != nil {
c.JSON(400, gin.H{"error": err.Error()})
return
}
// ...
}
-
@Param的第三个字段（true）表示是否必填，影响文档中字段的 required 标记 - 如果请求体是数组（如
[]model.User），注释写{array} model.User，不是{object} -
@Param不写body类型，swagger-ui 就不会渲染请求体输入区域
@Sumamry），整条接口就失效。文档生成是静态过程，别指望它“猜”你意图。 
