swag init 未生成 docs 目录是因为未扫描到 handler 函数：仅沿 main.go import 链递归解析，若 handler 所在包未被导入、置于 _test.go、路径含中文/空格、或 vendor 未加 --parseVendor 参数，均会导致静默跳过。
swag init 为什么没生成 docs 目录？
说明：这不是命令没运行，而是 swag 工具根本没扫描到你的 handler 函数——它只顺着 main.go 的 import 链递归解析，一旦 handler 所在包没被任何上层包 import，就会静默跳过。
实操建议：
立即学习“go语言免费学习笔记（深入）”；
- 确保
swag init -g main.go在项目根目录（含go.mod）执行，且main.go真的 import 了所有含 Swagger 注释的 handler 包 - 别把 handler 放在
_test.go文件里——swag默认忽略测试文件 - Windows 下路径含中文或空格会导致解析失败，项目路径必须纯英文、无空格
- 如果用了
vendor，加--parseVendor参数，否则 vendor 里的结构体定义不可见
@Success 200 {object} User 编译报错？
说明：swag 生成的 docs/docs.go 是硬编码引用结构体全名的，写 User 而不是 models.User，或返回指针却漏掉 *，都会导致编译失败，错误类似：undefined: User。
实操建议：
立即学习“go语言免费学习笔记（深入）”；
- 所有
@Param、@Success、@Failure中的类型必须带完整包名，例如models.User或*models.User - 结构体字段需有
json:tag，否则字段不会出现在文档响应示例中 - 修改过结构体后，必须重新运行
swag init，否则docs.go仍引用旧字段名
访问 /swagger/index.html 404？
说明：swag 只生成静态资源（docs/swagger.json 等），不自动注册路由。404 不是文档没生成，而是没挂载到 HTTP 服务上。
Alibabacloud Sdk Client Initialization For Golang
下载
初始化并管理阿里云SDK Go 客户端，涵盖 sync.Once 单例、goroutine 安全、endpoint 与 region 配置、VPC 端点及调试。
实操建议：
立即学习“go语言免费学习笔记（深入）”；
- Gin 项目必须显式调用：
r.GET("/swagger/*any", ginSwagger.WrapHandler(swaggerFiles.Handler)) - 路径前缀
/swagger必须和前端请求 URL 完全一致，少个斜杠或大小写错都会 404 - 确保已
import "your-module-name/docs"，否则ginSwagger拿不到元数据 -
swagger.NewHandler()或等价初始化逻辑，必须在gin.Default()之后、r.Run()之前
CI/CD 中 swag init 失败：cannot find package？
说明：swag 是静态分析工具，但它依赖 go list 能解析整个模块依赖图。CI 环境若没提前拉取依赖，或 go.mod 不完整，就会 panic。
实操建议：
立即学习“go语言免费学习笔记（深入）”；
- CI 脚本中，在
swag init前必须执行：go mod download - 不要跳过
go mod tidy，缺失的 indirect 依赖可能导致结构体解析中断 - swag 不读
vendor/，即使项目启用了 vendor，也得确保模块模式可用（即GO111MODULE=on）
Gin 项目里最常卡住的地方，其实是注释位置和 import 链——函数上方隔了一行空格、注释缩进了一个 tab、或者 handler 包被忘了 import，swag 就当它不存在。这些细节不报错，只沉默跳过。
