swag是go生态唯一稳定落地的api文档自动生成方案，仅通过解析源码注释生成swagger.json，不依赖运行时反射；需正确安装、指定扫描路径、规范package声明与注释格式，并手动挂载swagger ui路由。
swag 是 Go 生态中唯一稳定落地的 API 文档自动生成方案，它不依赖运行时反射，只靠解析源码注释生成 swagger.json。别指望 go doc 或 Gin 内置能力能输出 REST 文档——它们根本不是为这个设计的。
swag init 命令执行失败或生成空文档？先看这三件事
常见现象是跑完 swag init，docs/swagger.json 为空，或 paths 字段根本不存在。这不是注释写错了，而是工具压根没扫描到你的 handler 文件。
- 必须用
go install github.com/swaggo/swag/cmd/swag@latest安装（go get已弃用） - 必须在项目根目录（含
go.mod和main.go或路由入口的目录）执行；若路由分散在internal/handler、pkg/api，得显式指定：swag init -d internal/handler -d pkg/api - 所有被扫描的
.go文件必须有合法package声明，且不能是package main（除非它真写了r.GET()），否则会被跳过
@Param / @Success 注释报错或字段不显示？类型和位置必须严格匹配
swag 不认 Go 类型系统，也不推导参数来源。它只按注释字面解析，错一个词就静默跳过或报 ParseComment error。
-
@Param id path string true "用户ID"✅ ——path不能写成Path或PATH；类型只能是string、int、bool、float64，别写int64或uuid.UUID -
@Param req body models.UserCreate true "用户信息"✅ ——body参数必须指向一个已定义的结构体，且该结构体上方需有// @Model注释 -
@Success 200 {object} models.UserResponse✅ —— 结构体字段必须导出（首字母大写）、带json:tag（如Name string `json:"name"`），否则字段不会出现在 Model 树里 - 数组参数必须写成
type: array+items.type: string，不能简写为type: []string
Swagger UI 访问 /swagger/index.html 404 或空白？静态资源没挂对
生成 docs/ 目录只是产出文件，不等于自动注册路由。Gin/Echo/net/http 都需要手动挂载，且路径规则完全不同。
- Gin 用户：必须用
ginSwagger.WrapHandler(swaggerFiles.Handler)，且路由写法是r.GET("/swagger/*any", ...)——*any不能省，否则子资源（如/swagger/swagger-ui.css）全 404 - 别用
r.Static("/swagger", "./docs")：Swagger UI 是 SPA，依赖 History API 回退，必须由WrapHandler处理 - net/http 用户：用
http.Handle("/swagger/", http.StripPrefix("/swagger/", http.FileServer(http.Dir("./docs"))))，注意前缀对齐 - 务必确认
_ "your_project/docs"已导入（否则docs/docs.go不参与编译，swagger.json加载失败）
中文乱码、响应体显示 “object”、字段全空？检查源码硬性条件
文档加载后中文变 \u4f60\u597d，或点开 Schema 全是空对象，基本不是配置问题，而是代码层没满足 swag 的硬性要求。
- 所有 Go 源文件编码必须是 UTF-8（用
file -i handler.go检查；VS Code 右下角可切换） - 注释里不能混入不可见字符（比如从微信、Word 复制的引号、换行符）
- 结构体字段若用了
json:"-"或未导出（小写首字母），哪怕写了@Param，也不会出现在文档中 - 嵌套结构体必须也定义在可导入包下，或用
// @Model显式标记，否则swag认不出类型
swag init 扫不到文件、@Param 类型写错却报错模糊、或者挂了路由但 JS 加载 swagger.json 时 404——这些地方一错，整个文档就断链，而且没有明确提示。golang免费学习笔记（深入）：立即使用
在学习笔记中，你将探索golang的核心概念和高级技巧！
