swag init失败、/swagger/index.html 404、响应显示object、中文乱码等问题，根本原因是swag工具链与gin-swagger协作断点未对齐：需确保正确安装swag、在项目根目录执行并指定-d/-g参数、handler函数含完整注释（首行为@Summary）、正确挂载路由（含*any通配符）、空白导入docs包、结构体字段导出且带json tag、文件UTF-8无BOM编码，并生产环境禁用Swagger。
swag init 跑不通、/swagger/index.html 404、点开响应全是 object、中文变 \u4f60\u597d —— 这些不是 Swagger 本身的问题，而是 swag 工具链和 gin-swagger 的协作断点没对齐。
swag init 命令执行失败或生成 docs/ 为空
根本原因通常是工具链缺失、路径错位或注释格式不达标。swag 不会报错提示“你少写了 @Summary”，它只会静默跳过整个函数。
- 确认已安装 CLI：运行
swag -version，若报 command not found，请用go install github.com/swaggo/swag/cmd/swag@latest（Go 1.21+ 必须带@latest） - 必须在项目根目录执行：
swag init默认只扫描当前目录及子目录下属于同一 module 的.go文件；若 handler 分散在internal/handler或pkg/api，需显式指定swag init -d internal/handler -d pkg/api - 入口文件要带
-g：如果main()不在main.go，而在cmd/app/main.go，必须加swag init -g cmd/app/main.go，否则路由注册逻辑可能被漏掉 - 所有 handler 函数必须有完整注释块，且第一行是
// @Summary；缺这一行，该函数直接被忽略，docs/docs.go不更新，Swagger UI 就看不到接口
gin-swagger 挂载后访问 /swagger/index.html 报 404
这不是路由没注册，而是静态资源没走对处理流程。Swagger UI 是单页应用（SPA），依赖 History API 路由回退，不能用 router.Static() 粗暴挂载。
- 确保
swag init成功后存在docs/docs.go和docs/swagger.json；不存在说明上一步就失败了 - 注册方式必须是：
router.GET("/swagger/*any", ginSwagger.WrapHandler(swaggerFiles.Handler))—— 注意*any不能省，否则/swagger/swagger-ui.css这类子路径全 404 - 导入语句不能漏：
import _ "your-module-name/docs"（注意是 blank import），否则docs.SwaggerInfo不会被初始化，swaggerFiles.Handler拿不到数据 - 别把
docs/当普通静态目录：用router.Static("/docs", "./docs")是无效的，UI 加载会卡在doc.json404
@Param 或 @Success 字段不显示、响应体显示 “object” 或空字段
swag 不反射结构体，也不读取 Go 类型系统，它只认注释里写的字面量 + 显式声明的 @Model + 导出字段的 json: tag。
立即学习“go语言免费学习笔记（深入）”；
-
@Param id path int true "用户ID"✅ —— 路径/查询/请求头参数只能写基础类型：string、int、bool、float64；别写int64或uuid.UUID，否则报cannot find type definition -
@Param user body UserReq true "用户信息"✅ ——body后必须跟一个 struct 名，且该 struct 上方需有// @Model注释，否则 swag 不知道怎么生成 schema - 结构体字段必须导出（首字母大写）且带
json:tag，例如Name string `json:"name"`；若写成name string或Name string `json:"-"`，字段不会出现在文档中 - 中文乱码？检查文件编码是否为 UTF-8（无 BOM），且注释里的中文是直接写的，不是从其他编辑器粘贴进来的不可见字符
上线后 Swagger 页面空白或加载超时
问题不在前端，而在 docs/swagger.json 被暴露给了公网 —— 它包含所有接口路径、错误码、内部字段名甚至注释里的调试说明。
- 生产环境务必移除或条件编译掉 swagger 路由注册代码；别用
if os.Getenv("ENV") == "dev"这种运行时判断，而要用 build tag：//go:build dev+go run -tags=dev main.go - 若运维平台确需保留（如内网调试），至少加 Basic Auth 中间件，或限制 IP 段：
router.Use(func(c *gin.Context) { if !isInternalIP(c.ClientIP()) { c.AbortWithStatus(403); return } }) - 不要手动修改
docs/swagger.json：它是自动生成的，下次swag init会被覆盖；敏感字段应通过注释控制，比如用// @Security ApiKeyAuth替代裸写 token 示例
最常被忽略的一点：swag 不是“插件式”工具，它本质是源码分析器 —— 注释格式、package 声明、struct tag、build tag 全部构成它的输入契约。任何一个环节松动，生成结果就会断裂，但错误反馈极其安静。动手前先跑通一个最小可运行示例（含 main.go + 单个 handler + @Summary），比查半天日志更高效。
