Swagger页面打不开、404或空白，主因是三件事没做对：swag init未成功生成有效swagger.json、docs包未以下划线方式正确导入、ginSwagger.WrapHandler注册路径或方式错误。
Swagger 页面打不开、404、空白或报 no required "doc" found，基本就是三件事没做对：swag init 没跑成功、docs 包没下划线导入、ginSwagger.WrapHandler 注册姿势错了。其他都是细节问题。
swag init 为什么静默失败或不生成接口
swag init 不报错 ≠ 成功。它只扫描带 // @Summary 的具名函数，且严格依赖注释位置和格式：
- 注释必须紧贴 handler 函数上方，中间不能有空行；写在
func main()里或匿名函数里完全无效 -
@Param类型和位置必须匹配实际路由：路径参数用path，查询参数用query，JSON 请求体用body，写反了参数就消失 - 结构体类型必须可导出（首字母大写），且包路径要写全，比如
models.User，不能只写User - 执行时加
-d ./显式指定根目录，尤其当 handler 分散在handlers/或api/子目录下 - 生成后立刻检查
docs/swagger.json是否有"paths"字段——为空说明注释根本没被识别
main.go 里 docs 包导入必须带下划线
光跑 swag init 不够，docs/docs.go 里的 init() 函数必须被触发，否则 SwaggerInfo 不存在：
- import 必须是
_ "your-module-name/docs"，模块名必须和go.mod第一行完全一致（比如module github.com/xxx/myapp→ 就得写_ "github.com/xxx/myapp/docs"） - 不能写成
_ "./docs"或_ "docs"，Go 会直接忽略 - 这个 import 必须放在
main.go（或启动文件）的 import 列表里，不能藏在别的文件里 - 如果项目用了
go.work，确保swag init和运行程序都在主模块根目录下
注册 gin-swagger 路由不能少 WrapHandler
常见错误是把 docs.Handler 当成 handler 直接传进去，导致 panic 或 404：
- 正确写法是
r.GET("/swagger/*any", ginSwagger.WrapHandler(swaggerFiles.Handler)) -
WrapHandler是 gin-swagger 提供的适配器，不是swaggerFiles.Handler()（带括号是调用，返回值不是 gin.HandlerFunc） -
/swagger/*any中的*any是 Gin 的通配符语法，缺了它会导致子路径（如/swagger/index.html）404 - 如果部署在 Nginx 后面且有前缀（比如
/api-docs），需改用ginSwagger.URL("http://host/api-docs/doc.json")并配静态资源代理
部署后访问不到 /swagger/index.html 的真实原因
本地能跑通，部署后白屏或 404，大概率是构建环境与运行环境不一致：
-
swag init必须在最终打包的机器上运行（或 CI/CD 流水线中），不能只在开发机生成再复制docs/文件夹——因为docs/docs.go依赖当前 GOPATH 和模块路径 - 确保生产环境 PATH 包含
$GOPATH/bin，否则swag命令找不到，CI 脚本里要显式加export PATH=$PATH:$GOPATH/bin - 如果用 Docker，
Dockerfile中要在go build前执行swag init，且工作目录设为项目根目录 - 检查
docs/目录是否被 .gitignore 误删，或构建脚本漏掉了该目录
最常被跳过的环节是：没验证 docs/swagger.json 内容是否真实包含接口定义。只要这一步没卡死，后面全是配置顺序和路径问题。
