swag init 报错主因是缺失或格式错误的 // @title 等注释，必须位于 main 包文件中且连续无空行；类型需显式 import、结构体及字段均须首字母大写并带 json tag；docs 目录须与二进制同级；CI 中需指定 -g 入口文件路径。
swag init 报错找不到 // @title 注释
Swagger 文档生成失败，最常见原因是 swag init 扫不到基础 API 元信息。它不读代码逻辑，只靠特定格式的 Go 注释（叫 “swag comments”）提取标题、描述、版本等——没写或写错位置，就直接报错或生成空文档。
-
// @title必须出现在 main 包的某个 .go 文件里（通常是main.go或docs/docs.go），且不能被注释掉、不能在函数体内 - 注释块必须连续，中间不能有空行，例如：
// @title My API<br>// @version 1.0<br>// @description This is a sample server.
- 如果用的是模块化项目（如
cmd/xxx/main.go），要确保swag init的工作目录包含该文件，或显式指定：swag init -g cmd/myapp/main.go - Go 1.21+ 默认开启
GO111MODULE=on，但 swag 不解析 go.mod，只认文件路径，别指望它自动找入口
controller 里写 @Success 却不显示返回示例
写了 // @Success 200 {object} model.User，但网页里 Response Schema 还是空的，大概率是类型没被正确识别——swag 不递归扫描所有包，只看当前文件 + 显式 import 的类型，且要求结构体可导出、字段可导出。
- 确认
model.User在当前文件有 import，且User首字母大写（否则 swag 当作私有类型跳过） - 字段也要首字母大写，且最好加 struct tag，比如
Name string `json:"name"`；没 tag 的字段可能被忽略或显示为interface{} - 如果返回的是指针（
*model.User）或切片（[]model.User），注释里也得写全：{object} model.User和{array} model.User含义不同，后者才生成数组示例 - 嵌套结构体（如
User.Profile *Profile）需要Profile类型也在同一包或已 import，否则只显示object而无字段细节
启动 docs 路由后页面 404 或 CSS 加载失败
调用 httpSwagger.WrapHandler 注册路由后，访问 /swagger/index.html 返回 404，或者页面空白、控制台报 swagger-ui.css:1 Failed to load resource，本质是静态资源没正确挂载。
Golang Uber Dig
下载
使用 uber-go/dig 在 Golang 中实现依赖注入——基于反射容器，提供 Provide/Invoke、dig.In/dig.Out 参数与结果对象，支持命名依赖等
- 确保
swag init成功执行，生成了docs/目录（含docs.go、swagger.json等），这个目录必须和二进制在同一级，否则httpSwagger找不到文件 - 不要手动改
docs/doc.go里的docs.SwaggerInfo路径字段，它只影响 JSON 内容，不影响文件服务路径 - 使用
httpSwagger.Handler()时，别漏掉括号：httpSwagger.Handler()是函数调用，返回 handler；httpSwagger.Handler是函数地址，会导致 panic - 如果你用的是 Gin，注册方式是
r.GET("/swagger/*any", ginSwagger.WrapHandler(swaggerFiles.Handler))；用 net/http 就是http.Handle("/swagger/", http.StripPrefix("/swagger/", httpSwagger.Handler()))
CI 环境下 swag init 失败：no Go files
本地能跑通，CI 流水线里执行 swag init 却提示 no Go files found，不是代码问题，是 swag 默认只扫当前目录下的 .go 文件，而 CI 常把源码放在子目录（如 src/）或用了多阶段构建，工作目录不对。
立即学习“go语言免费学习笔记（深入）”；
- 明确指定扫描路径：
swag init -g main.go -o ./docs，其中-g指向主入口文件，-o指定输出目录 - 确保 CI 步骤中执行
swag init前，已经go mod download完成，否则依赖包里的类型（如github.com/swaggo/http-swagger）可能无法解析 - Swag v1.8+ 支持
--parseDependency参数，但会显著拖慢生成速度，非必要不加；多数情况只需保证-g指向的文件 import 了所有要用到的模型类型 - 如果项目用了 Go Workspace（
go.work），swag 不识别 workspace，必须 cd 进具体 module 目录再执行
真正卡住人的往往不是语法，而是 swag 对“可见性”的苛刻要求：它只认当前文件 + 直接 import 的类型 + 可导出的结构体字段。少一个条件，Schema 就变 object，点开全是问号。
