使用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"。
