swag是Go生态中唯一稳定落地的API文档自动生成方案，需正确配置扫描路径、package声明、注释格式及结构体tag才能生成完整文档。
swag 是当前 Go 生态中唯一能稳定落地的 API 文档自动生成方案，其他框架内置能力（如 GoFrame 的 net/goai）仍处于实验阶段，生产环境首选仍是 swag。
swag init 扫不到接口？先确认扫描路径和 package
常见现象是执行 swag init 后生成的 docs/swagger.json 里 paths 为空，或浏览器打开 Swagger UI 只显示首页、没有接口列表。这不是注释写错了，而是 swag 根本没看到你的 handler 文件。
- 默认只扫描当前目录及子目录下属于同一 module 的
.go文件；如果 handler 分散在internal/handler、pkg/api等路径，必须显式指定：swag init -d internal/handler -d pkg/api - 入口文件（如
cmd/app/main.go）要用-g指定：swag init -g cmd/app/main.go，否则可能漏掉跨包调用的路由注册逻辑 - 被扫描的文件不能是
package main（除非它真包含r.GET()这类路由注册），否则 swag 会跳过——推荐把路由逻辑单独放在package router或package api - 所有 handler 函数所在文件必须有合法
package xxx声明，且不能含语法错误，否则整个文件被忽略
@Param 和 @Success 写错类型？记住 swag 不认 Go 类型系统
报错类似 cannot find type definition for "uuid.UUID" 或 unknown type "string"，本质是 swag 的类型解析器和 Go 编译器不一致：它只认基础类型名和已用 @Model 显式声明过的 struct。
-
@Param id path string true "用户ID"✅ —— 路径/查询/请求头参数只能用string、int、bool、float64，别写int64或uuid.UUID -
@Param user body model.User true "用户信息"✅ —— 请求体（in: body）必须指向一个已定义的 struct，且该 struct 上方需有// @Model注释 -
@Success 200 {object} model.UserResponse✅ —— 结构体必须导出（首字母大写），字段必须带json:tag，否则字段不会出现在 schema 中 - 数组参数写法：
@Param ids query array true "ID列表" collectionFormat:multi items.type:string，不能简写为type: []string
中文乱码、响应体显示 “object”、字段全空？检查三个硬性条件
文档加载后中文变 \u4f60\u597d，或点开响应 schema 全是空对象，大概率不是配置问题，而是代码层面没满足 swag 的硬性要求。
- 源文件编码必须是 UTF-8（用
file -i handler.go检查），VS Code 右下角可切换编码并重存 - 每个 handler 函数上方必须紧贴着写
// @Summary，中间不能有空行；没这行，接口标题就是 “undefined” - 每个 handler 必须配
// @Success 200 {object} Xxx，且Xxx对应的 struct 所在包已 import，字段有json:"field_name"，嵌套结构要逐层加 tag -
time.Time字段建议显式加time_format:"2006-01-02T15:04:05Z"，否则可能被转成数字时间戳，前端无法识别
Gin/Echo/net/http 都能用，但 Swagger UI 路由必须手动挂载
swag init 只生成 docs/ 目录，不自动暴露 UI。不挂载路由，访问 /swagger/index.html 就是 404。
- Gin 用户：
import github.com/swaggo/gin-swagger和github.com/swaggo/files，然后r.GET("/swagger/*any", ginSwagger.WrapHandler(swaggerFiles.Handler)) - Echo 用户：
import github.com/swaggo/echo-swagger，然后e.GET("/swagger/*", echoSwagger.WrapHandler(echoFiles.Handler)) - net/http 用户：
http.Handle("/swagger/", http.StripPrefix("/swagger/", http.FileServer(http.Dir("./docs"))))，注意路径前缀必须匹配 - GoFrame 用户暂不推荐直接集成 swag，其原生
net/goai模块虽支持 OpenAPI 3.0，但对复杂嵌套响应、中间件透传等场景兼容性尚未稳定
最常被忽略的一点：swag 生成的是静态 JSON + 前端资源，它不运行时分析代码，也不依赖反射。所有文档内容完全来自注释文本和结构体 tag —— 漏一个 json:，字段就消失；少一行 @Success，整个响应体就变空。这不是 bug，是设计使然。
