swag init 未生成 docs 是因注释缺失 @title/@version、未置于 main.go 顶部、未在项目根目录执行，或未指定 -d/-g 参数；需确保注释格式正确、结构体字段导出且含 json tag、blank import docs 包，并用 *any 路由挂载。
swag init 什么都没生成，docs/ 目录为空
这不是网络问题或权限问题，而是 swag 工具根本没扫描到有效注释。它不会报错，只会静默跳过——你写的注释只要缺 @title 或 @version，或者没放在 main.go 顶部（package 声明之后、import 之前），swag init 就不生成任何内容。
- 执行前先确认：
swag -version能输出版本号；若提示 command not found，说明$GOPATH/bin没进 PATH，别绕开，直接补路径 -
swag init必须在项目根目录运行（即包含go.mod的目录），且默认只扫描当前目录及子目录下的.go文件；如果 handler 分散在internal/handler或pkg/api，必须显式加-d internal/handler -d pkg/api - 如果
main()不在main.go，而在cmd/app/main.go，必须加-g cmd/app/main.go，否则全局注释读不到，整个文档骨架就塌了 - 生成后立刻检查：
docs/swagger.json是否有非空 JSON 内容；空文件 = 注释格式错（比如//@Summary少了个空格，或换行符是 CRLF）
访问 /swagger/index.html 报 404
不是路由没注册，是静态资源加载路径断了。Swagger UI 是单页应用，所有子路径（如 /swagger/swagger-ui.css）都得由同一个 handler 统一接管，靠 *any 通配才能兜住。
- 注册路由必须写成：
r.GET("/swagger/*any", ginSwagger.WrapHandler(swaggerFiles.Handler))——*any不能省，也不能写成/**或* - 必须 blank import docs 包：
import _ "your-module-name/docs"（模块名严格匹配go.mod第一行，比如module github.com/xxx/myapp就得写_ "github.com/xxx/myapp/docs"） - 别用
r.Static()挂载./docs：这会导致doc.json404，UI 卡死在 loading 状态 - 确保
docs/docs.go文件真实存在且已重新生成；删掉旧 docs 目录再跑一次swag init更稳妥
@Param 或 @Success 显示 object 或字段全空
swag 不反射结构体，也不读 Go 类型系统。它只认你注释里写的字面量，且要求结构体字段必须导出 + 有 json: tag，否则渲染就是空。
-
@Param user body models.User true "用户请求体"中的models.User必须是完整包路径，不能只写User；如果结构体在当前文件，也得写成.User（带点） - 结构体字段名首字母必须大写（导出），且每个字段都要有
json:tag，比如ID uint `json:"id"`；漏一个，那个字段就不显示 -
@Success 200 {object} models.UserResponse中的UserResponse如果字段全是小写或没 tag，Swagger 就渲染成{}或object - 中文注释务必保存为 UTF-8 无 BOM 编码，否则变成
\u4f60\u597d；VS Code 默认就是，但某些编辑器（如老版 Sublime）会偷偷加 BOM
生产环境还能开 Swagger 吗
不能。gin-swagger 会暴露全部接口路径、参数、响应结构，甚至可能泄露内部错误信息，线上开启等于把钥匙交给攻击者。
- 启动时加构建标签控制：
if gin.Mode() == gin.DebugMode { r.GET("/swagger/*any", ... ) } - 更稳妥的是用构建约束：在
swagger.go文件顶部加//go:build debug，然后只在调试构建时编译进去 - CI/CD 流水线中禁止打包 docs 目录；Dockerfile 里别 COPY docs/，也别 go install swag
- 即使关掉路由，也要确认
docs/目录没被 Nginx/Apache 误配置为静态服务，否则swagger.json仍可直访
真正卡住人的从来不是“怎么装”，而是注释位置错一位、import 少个下划线、路径少个星号——这些细节不验证，文档永远是白屏。
golang免费学习笔记（深入）：立即使用
在学习笔记中，你将探索golang的核心概念和高级技巧！
