swag是Go生态唯一稳定落地的API文档自动生成方案，通过静态解析源码注释生成OpenAPI 3.0文档；需正确指定扫描路径（-d）、入口文件（-g），确保handler文件非package main、含合法注释及导出结构体，并手动挂载Swagger UI路由。
swag 是 Go 生态中唯一能稳定落地的 API 文档自动生成方案，它不依赖运行时反射，只靠静态解析源码注释生成 OpenAPI 3.0 文档。别指望 go doc 或框架内置能力能输出 REST 文档——它们根本不是为这个设计的。
swag init 扫不到接口？检查扫描路径和入口文件
执行 swag init 后 docs/swagger.json 中 paths 为空，或 Swagger UI 显示首页但无接口列表，问题几乎总出在“没扫到 handler 文件”。
- 默认只扫描当前目录及子目录下属于同一 module 的
.go文件；若 handler 分散在internal/handler、pkg/api等路径，必须显式指定：swag init -d internal/handler -d pkg/api - 入口文件（如
cmd/app/main.go）要用-g指定：swag init -g cmd/app/main.go，否则可能漏掉跨包注册的路由逻辑 - 被扫描的文件不能是
package main（除非它真包含r.GET()），推荐把路由逻辑单独放在package router或package api - 所有 handler 文件必须有合法
package xxx声明，且不能含语法错误，否则整个文件被跳过
@Param 和 @Success 字段不显示？类型和位置必须严格匹配
swag 不认 Go 类型系统，也不推导参数来源。它只按注释字面解析，错一个词就静默跳过或报 ParseComment error。
Golang Uber Dig
下载
使用 uber-go/dig 在 Golang 中实现依赖注入——基于反射容器，提供 Provide/Invoke、dig.In/dig.Out 参数与结果对象，支持命名依赖等
-
@Param id path string true "用户ID"✅ ——path不能写成Path或PATH；类型只能是string、int、bool、float64，别写int64或uuid.UUID -
@Param req body models.UserCreate true "用户信息"✅ ——body参数必须指向一个已定义的结构体，且该结构体上方需有// @Model注释 -
@Success 200 {object} models.UserResponse✅ —— 结构体字段必须导出（首字母大写）、带json:tag（如Name string `json:"name"`），否则字段不会出现在 schema 里 - 数组参数必须写成
type: array+items.type: string，不能简写为type: []string
访问 /swagger/index.html 404 或空白？静态资源没挂对
生成 docs/ 目录只是产出文件，不等于自动注册路由。Gin/Echo/net/http 都需要手动挂载，且路径规则完全不同。
立即学习“go语言免费学习笔记（深入）”；
- 确保
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.json 404
上线后 Swagger 页面空白或加载超时？别暴露 docs/ 给生产环境
Swagger UI 会直接读取 docs/swagger.json，而这个文件默认包含所有接口细节，包括敏感路径、内部错误码，甚至注释里的调试说明。
- 开发期用
ginSwagger没问题；上线前务必移除或条件编译掉相关路由注册代码 - 若需保留（如内部运维平台），至少用中间件限制 IP 段或加 Basic Auth，别让
/swagger/可公开访问 -
swag init -o ./docs_prod可指定输出目录，配合构建脚本做环境隔离
