swagger文档在gin中失败主因是swag init未生效、docs包未blank import或路由挂载错误；需确保@summary在首行、全局注释完整、-d指定路径、-g指向main文件、utf-8无bom编码，并正确注册带**any的路由及blank import。
Swagger 文档在 Gin 项目里跑不起来，90% 是因为 swag init 没生效、docs 包没 blank import、或者路由挂载写错了——不是 Swagger 不行，是协作链路断在了某个静默环节。
swag init 总是生成空 docs/ 目录
这个命令不会报错，但会跳过所有不符合格式的注释。常见原因有：
-
@Summary缺失或不在 handler 函数注释块第一行：哪怕只少一个空格，整个函数就被忽略 - 全局注释没放在
main.go顶部（package声明后、import前），且漏了@title或@version - handler 分散在
internal/handler或pkg/api，但没用-d指定路径：swag init -d internal/handler -d pkg/api -
main()不在main.go，比如在cmd/app/main.go，必须加-g cmd/app/main.go - 文件编码不是 UTF-8 无 BOM：Windows 上用记事本保存容易带 BOM，导致解析失败
访问 /swagger/index.html 显示 404 或空白页
这不是路由没注册，而是静态资源加载失败。关键点：
- 必须存在
docs/docs.go和docs/swagger.json—— 如果没有，说明上一步swag init就失败了 - 路由注册必须带通配符：
r.GET("/swagger/*any", ginSwagger.WrapHandler(swaggerFiles.Handler))，*any不能省 - 必须 blank import
docs包：import _ "your-module-name/docs"（模块名严格匹配go.mod第一行） - 别用
r.Static("/swagger", "./docs")—— Swagger UI 是 SPA，依赖 History API，Static无法处理子路径请求
@Param 和 @Success 显示 “object” 或字段为空
Swag 不反射结构体，它只认注释里写的类型和包路径：
-
@Param user body models.User true "用户数据"中的models.User必须是已定义、导出的结构体，且字段带json:tag - 如果结构体在当前包，写
User即可；跨包必须写全路径，如github.com/yourorg/yourapp/models.User -
@Success 200 {object} models.UserResponse里的UserResponse同样要满足导出+json tag - 中文乱码（显示
\u4f60\u597d）通常是源文件用了 GBK 编码，改用 UTF-8 无 BOM 即可
最常被忽略的是 blank import 那一行——没它，docs.SwaggerInfo 根本不会初始化，ginSwagger.WrapHandler 拿不到任何数据，页面自然空白。检查 go.mod 里的模块名是否和 import 语句完全一致，多一个空格或大小写错误都会失效。
golang免费学习笔记（深入）：立即使用
在学习笔记中，你将探索golang的核心概念和高级技巧！
