swag是go生态唯一稳定落地的api文档自动生成方案，通过静态解析注释生成openapi 3.0文档；需在根目录执行swag init，显式指定-g入口和-d扫描路径，handler文件不能为package main，@param/@success类型须严格匹配基础类型或已声明结构体，字段必须导出且带json:tag。
swag 是当前 Golang 生态中唯一稳定落地的 API 文档自动生成方案，其他工具（如 GoFrame 的 goai）仍处于实验阶段。它不依赖运行时反射，只靠静态解析注释，生成标准 OpenAPI 3.0 的 swagger.json，再交由 UI 渲染——这意味着你改完代码、补完注释，文档就同步更新，没有延迟。
swag init 扫不到 handler？先检查这 4 个硬性条件
执行 swag init 后 docs/swagger.json 里 "paths":{} 或接口列表为空，基本不是注释写得不够多，而是根本没被扫描到：
- 必须在项目根目录执行（即包含
main.go或server.go的目录），不是cmd/、internal/或api/子目录 - 命令需显式指定入口：若
main()在cmd/app/main.go，必须加-g cmd/app/main.go - 若 handler 分散在
internal/handler和pkg/api，要用-d internal/handler -d pkg/api显式声明扫描路径 - 所有 handler 函数所在文件必须是合法
package api或package handler，不能是package main（除非该文件真写了r.GET()）
@Param / @Success 写错一个字符，字段就消失
swag 对注释语法极其敏感，类型引用、位置标识、必填标记缺一不可：
-
// @Param id path int true "user ID"✅；写成int64、uuid.UUID或漏掉true就会丢参数 -
// @Success 200 {object} model.User✅；User缺包名、或结构体未import "model"，字段直接不出现 -
// @Success 200 {array} model.User✅；{array}单独写，没指定元素类型，schema 里就是空数组 - 请求体参数必须用
body位置：// @Param user body model.UserCreate true "用户信息"，写成query或path会静默忽略
结构体字段不显示？90% 是没加 json: tag
swag 不看 Go 字段名，只认 json: tag。哪怕字段叫 UserName 且首字母大写，只要没写 json:"user_name"，就不会进 schema：
- 导出字段（首字母大写）是前提，但不是充分条件
- 嵌套结构体也要逐层加 tag，否则深层字段不出现
- 忽略字段用
json:"-"，swag会跳过 -
time.Time建议显式写json:"created_at" time_format:"2006-01-02T15:04:05Z"，否则可能转成 float64 时间戳
Gin 中挂 Swagger UI 路由，少一行就 404
生成 docs/ 目录只是第一步。不注册路由，访问 /swagger/index.html 必定 404：
- 导入两个包：
github.com/swaggo/gin-swagger和github.com/swaggo/files - 在
r := gin.Default()之后加：r.GET("/swagger/*any", ginSwagger.WrapHandler(swaggerFiles.Handler)) - 注意：必须引入自动生成的
docs包（如_ "your-project/docs"），否则swaggerFiles.Handler会 panic - Docker 构建时要显式
COPY docs/ docs/，否则容器里没静态资源
json: tag、新增了泛型封装，却忘了同步更新 @Param 类型或 @Success 模板——这时文档就变成了“可信但不可信”的东西。大量免费API接口：立即使用
涵盖生活服务API、金融科技API、企业工商API、等相关的API接口服务。免费API接口可安全、合规地连接上下游，为数据API应用能力赋能！
