swag init 报错或 Swagger UI 无接口的根本原因是工具链未对齐、扫描路径未指定或注释格式不合规；必须用 go install 安装并确保 $PATH 包含 $GOBIN，显式指定 -d 和 -g 参数，注释需紧贴函数且无空行，结构体字段须导出并带 json tag。
Go 环境装好但 swag init 报 command not found，或者生成了 docs/docs.go 却在 Swagger UI 里看不到接口——问题几乎都出在工具链没对齐、扫描路径没指定、或注释格式被忽略。不是代码写得不对，是 swag 的解析规则和你预期的不一致。
swag CLI 安装失败或找不到命令
根本原因不是没下载，而是二进制没进 $PATH，或用了已失效的安装路径。
-
go install github.com/swaggo/swag/cmd/swag@latest是 Go 1.21+ 唯一推荐方式；go get已废弃，且github.com/go-swagger/go-swagger/cmd/swagger地址在 2026 年已彻底不可用 - 装完必须验证：
swag --version能输出版本号才算成功；如果报 command not found，请检查$GOPATH/bin（或$GOBIN）是否在 shell 的$PATH中 - macOS/Linux 用户常漏掉
source ~/.zshrc；Windows 用户需重启 PowerShell 才能读取新环境变量
swag init 扫不到接口，docs/swagger.json 里 paths 为空
swag 不会跨目录猜路由逻辑，它只扫你明确告诉它的 .go 文件，且要求这些文件里有合法的 package 声明和无语法错误。
- 默认只扫当前目录及子目录；若路由分散在
internal/handler和pkg/api，必须显式加-d参数：swag init -d internal/handler -d pkg/api - 入口文件（如
cmd/app/main.go）要用-g指定：swag init -g cmd/app/main.go，否则可能漏掉router := gin.New()之后的注册逻辑 - handler 文件不能是
package main（除非它真写了r.GET()），建议统一用package handler或package api - 任何 .go 文件只要含语法错误（比如少个括号、导包没用），整份文件会被跳过，不报错也不提示
Swagger UI 打开空白或 404
不是 Gin 路由没注册，而是静态资源没挂对路径，或 docs/docs.go 没被 import。
立即学习“go语言免费学习笔记（深入）”；
- 必须确保
swag init成功后，项目根目录下存在docs/docs.go和docs/swagger.json -
docs/docs.go必须被 import：在main.go顶部加一行import _ "./docs"（注意路径是相对路径，且带下划线） - Gin 挂载必须用
ginSwagger.WrapHandler，不能用router.Static()：r.GET("/swagger/*any", ginSwagger.WrapHandler(swaggerFiles.Handler))——*any不能省，否则/swagger/swagger-ui.css这类子资源全 404 - 挂载语句必须在
gin.Default()之后、r.Run()之前；顺序反了，中间件不会生效
@Summary 和 @Success 注释不生效，字段全空或显示 “object”
swag 不反射结构体，也不读函数签名，它只认紧贴函数上方、格式严丝合缝的注释块。
-
// @Summary必须在函数正上方，且**前后都不能有空行**；写成/* @Summary ... */或缩进的// @Summary都无效 -
// @Success 200 {object} model.UserResponse中的model.UserResponse必须是已导出 struct（首字母大写），且每个字段必须有json:tag；type User struct { Name string }会丢失Name字段，必须写Name string `json:"name"` - 时间字段别依赖默认行为：
CreatedAt time.Time `json:"created_at" time_format:"2006-01-02T15:04:05Z"`，否则文档里可能变成数字时间戳 - body 类型参数必须用
// @Param user body model.User true "用户信息"，其中model.User要有// @Model注释，且不能是*User或map[string]interface{}
最易被忽略的是：swag 解析完全脱离运行时，所有依赖都靠静态文本匹配。哪怕一个空格、一个换行、一个未导出字段，都会导致整个接口从文档里消失——它不会报错，只会静默跳过。
