swag init 生成 docs/ 失败需检查三件事：一要确保已安装 swag CLI 工具；二须在项目根目录执行命令；三所有 handler 函数必须含完整注释块且以 // @Summary 开头。
用 swag init 生成 docs/ 目录失败？检查这三件事
Swagger 文档在 Go 里不是“开箱即用”，swag init 命令必须在含正确注释的 Go 文件所在目录执行，且依赖 swag CLI 工具已安装并可访问。
- 确保已通过
go install github.com/swaggo/swag/cmd/swag@latest安装（Go 1.21+ 推荐用@latest，别用go get） -
swag init必须运行在项目根目录（即包含main.go或 API 路由定义的包目录），否则找不到package main或无法解析导入路径 - 所有用于生成文档的 HTTP handler 函数必须有完整注释块，且开头含
// @Summary，缺一则整个函数被跳过，docs/docs.go不会更新
为什么 gin-swagger 访问 /swagger/index.html 报 404？
这不是路由没注册，而是静态文件服务路径没对齐。Gin 默认不自动托管 docs/ 下的前端资源，需显式挂载。
- 确认
swag init成功后，项目下存在docs/docs.go和docs/swagger.json - 在 Gin 初始化后，加一行：
router.GET("/swagger/*any", ginSwagger.WrapHandler(swaggerFiles.Handler))—— 注意/swagger/*any中的*any不能省，否则子路径（如/swagger/swagger-ui.css）全 404 - 别把
docs当普通静态目录用router.Static()挂载：Swagger UI 是单页应用，依赖 History API，必须走ginSwagger.WrapHandler处理路由回退
// @Param 注释写错导致字段不显示？看参数位置和类型声明
Swagger 解析参数只认注释里的 @Param，和函数签名无关。它不会反射结构体字段，也不会猜你传的是 query 还是 body。
- 路径参数（如
/user/{id}）必须写// @Param id path int true "用户ID"，其中path不能写成Path或PATH - Query 参数用
query，Body 用body，且body后必须跟结构体名（如UserReq），该结构体需有swaggertypetag 或导出字段 - 如果结构体字段用了
json:"-"或未导出（小写首字母），即使写了@Param，字段也不会出现在文档中
上线后 Swagger 页面空白或加载超时？别暴露 docs/ 给生产环境
Swagger UI 会直接读取 docs/swagger.json，而这个文件默认包含所有接口细节，包括敏感路径、内部错误码，甚至注释里的调试说明。
立即学习“go语言免费学习笔记（深入）”；
- 开发期用
ginSwagger没问题；上线前务必移除或条件编译掉相关路由注册代码 - 若需保留（如内部运维平台），至少用中间件限制 IP 段或加 Basic Auth，别让
/swagger/可公开访问 -
swag init -o ./docs_prod可指定输出目录，配合构建脚本把文档分离，避免误打包进生产镜像
最常被忽略的其实是注释格式的空格和换行：多一个空格、少一个引号、@Success 后没写状态码，都会让整段注释失效——swag 不报错，只是静默跳过。建议每次改完注释都手动跑一遍 swag init -v 看输出日志。
