swagger ui打不开是因为docs包未导入或路由路径错误；必须显式导入docs包并严格使用/swagger/*路径；结构体需同模块或通过@modelspackage指定；字段须大写且带example tag；生产环境应禁用该路由。
swag init 生成 docs/ 后，Swagger UI 页面打不开？
不是代码没跑起来，而是 docs 包没被导入、或路由没配对。Go 程序启动时不会自动加载 docs 目录里的 docs.go，必须显式导入一次（哪怕只是 blank import）。常见错误是只运行了 swag init，却忘了在 main.go 里加这一行：
import _ "your_project_path/docs"
同时，gin-swagger 的路由必须严格匹配路径前缀：/swagger/*any 是硬性约定，不能写成 /docs 或 /api/swagger。否则请求进不来 Handler，浏览器只会看到 404。
-
swag init必须在项目根目录执行，且默认只扫描当前目录及子目录；若 handler 分散在多个 module，需用-g指定入口文件，如swag init -g internal/server/main.go - 如果用的是 Gin，
ginSwagger.WrapHandler(swaggerFiles.Handler)必须传入swaggerFiles.Handler，不是http.FileServer或自定义 mux - 访问地址固定为
/swagger/index.html，不是/swagger/或/swagger.json—— 后者是 raw 文件，不带 UI
@Param 和 @Success 中的结构体类型找不到？
Swag 不会跨 module 自动解析结构体，尤其当 @Success 200 {object} models.User 里的 models.User 在另一个 Go module 时，swag init 会静默跳过该接口，文档里直接消失。这不是 bug，是设计限制。
解决方法只有两个：
- 把模型定义和 handler 放在同一个 module（最省事）
- 在 main.go 顶部加全局注释：
// @modelsPackage github.com/yourname/project/models，告诉 Swag 去哪找类型
另外注意：结构体字段必须首字母大写（导出），且 JSON tag 要清晰。比如 UserName string `json:"user_name"` 没问题，但 userName string（小写开头）会被忽略，导致 Swagger UI 里响应体显示为空。
在线调试时参数没自动填充、body 无法编辑？
Swagger UI 默认依赖 OpenAPI 规范里的 schema 描述。如果 @Param 或 @Success 只写了类型名，没提供字段级定义，UI 就只能显示“string”或“object”，没法展开编辑。
补救方式很简单，在 struct 定义里加 example tag：
使用 uber-go/dig 在 Golang 中实现依赖注入——基于反射容器，提供 Provide/Invoke、dig.In/dig.Out 参数与结果对象，支持命名依赖等
type LoginRequest struct {
Email string `json:"email" example:"test@example.com"`
Password string `json:"password" example:"123456"`
}
这样 UI 里点击 “Try it out” 后，请求体就会预填示例值，还能手动改。同理，路径参数、查询参数也支持 default 和 example，比如：
// @Param page query int false "页码" default(1) example(2)
不加这些，UI 就只能靠用户自己拼 JSON，体验断层。
生产环境要不要暴露 /swagger/ 路由？
不要。Swagger UI 是开发调试工具，不是生产接口。它自带完整请求发起能力，等于把 Postman 嵌进了你的服务里——一旦暴露，攻击者能直接调用任意接口，绕过鉴权逻辑（除非你额外加中间件拦截）。
最稳妥的做法是条件编译：
if gin.Mode() == gin.DebugMode {
r.GET("/swagger/*any", ginSwagger.WrapHandler(swaggerFiles.Handler))
}
或者用构建 tag：
//go:build swagger package main import _ "your_project/docs"
然后只在本地用 go run -tags swagger main.go 启动。CI/CD 构建时去掉 tag，docs 包根本不会被链接进去，二进制里连相关代码都没有。
真正容易被忽略的是：即使关了路由，swagger.json 文件如果放在静态目录下且未设权限，仍可能被直接下载。所以生成后最好删掉或移出公开路径。
golang免费学习笔记（深入）：立即使用
在学习笔记中，你将探索golang的核心概念和高级技巧！
