go-swagger 生成失败：找不到 swagger generate spec 命令
根本原因是 go-swagger 没装对，或没进 $PATH。它不是 go get 直接装完就能用的二进制工具，得手动下载预编译版本或从源码构建。
实操建议：
立即学习“go语言免费学习笔记（深入）”；
- 优先用官方推荐方式：
curl -sSL https://raw.githubusercontent.com/go-swagger/go-swagger/master/install.sh | sh，它会自动下载、校验、放进$GOPATH/bin - 确认
$GOPATH/bin已加入$PATH（常见坑：装完了但 shell 找不到命令） - 别用
go install github.com/go-swagger/go-swagger/cmd/swagger@latest—— Go 1.21+ 后这个路径已失效，新地址是github.com/go-swagger/swagger/cmd/swagger，但仍有兼容问题，不推荐 - 验证是否生效：
swagger version能输出版本号才算成功
Gin 项目加 Swagger UI：为什么 gin-swagger 不显示接口？
绝大多数情况是路由注册顺序错了，或者没正确挂载 swaggerFiles 静态资源。
实操建议：
立即学习“go语言免费学习笔记（深入）”；
-
swagger.NewHandler()必须在gin.Default()或gin.New()之后、r.Run()之前调用 - 必须显式挂载 swagger UI 的静态文件：
r.GET("/swagger/*any", ginSwagger.WrapHandler(swaggerFiles.Handler))—— 少了/swagger/*any这段路径，页面打开空白 - 确保生成的
docs/docs.go文件存在且被 import（Gin-Swagger 依赖它读取注释元数据），别忘了运行swag init - 如果用了模块路径（
go mod），swag init要加-g参数指定go文件入口，比如swag init -g main.go
注释写法不对：@Summary 写了但 Swagger UI 里还是空
Go-Swagger 对注释格式极其敏感，只认紧贴在函数声明**正上方**的块注释，且必须以 // @ 开头，中间不能有空行、不能缩进、不能混用 /* */。
实操建议：
立即学习“go语言免费学习笔记（深入）”；
- 正确姿势：
// @Summary 获取用户信息 // @ID get-user // @Accept json // @Produce json // @Param id path int true "用户ID" // @Success 200 {object} model.User // @Router /users/{id} [get] func GetUser(c *gin.Context) { ... } - 错误姿势：注释写在函数内部、用
/* */包裹、前面有空行、@后多空格或拼错（如@summery） -
@Param类型必须和实际路由/参数一致：path对应:id，query对应 URL 查询参数，body对应c.ShouldBindJSON()的结构体 - 结构体字段要加
json:tag，否则@Success或@Failure里看不到字段
CI/CD 中 swag init 失败：找不到依赖或 go.mod 错乱
swag 是纯静态分析工具，但它会尝试解析 import 路径，一旦依赖未下载或 go.mod 不完整，就会 panic 报错，比如 cannot find package 或 no required module provides package。
实操建议：
立即学习“go语言免费学习笔记（深入）”；
- CI 环境务必先执行
go mod download，确保所有依赖拉下来 - 不要在
vendor模式下跳过go mod——swag不读vendor/，只认go list能看到的包 - 若项目用了 replace，确保
swag init运行时的 GOPROXY 和本地一致，否则可能解析错路径 - 建议把
swag init放在构建前一步，并加-o ./docs明确输出目录，避免默认行为因环境差异出错
文档生成这事，核心就两件事：注释得紧贴函数、命令得在正确路径下跑通。其他所有报错，八成是这两处漏了空格、少了个斜杠，或者没意识到 swag init 其实是个需要完整 Go 构建环境的“假静态”工具。
