swag init 报 “cannot find package” 的根本原因是 swag 不读 go.mod，需先运行 go mod tidy 拉取依赖；@Param 注释须紧贴 handler 且格式正确；托管 Swagger 需导入 docs 包并注册路由；全局注释 @title、@version、@BasePath 缺一不可且位置格式严格。
swag init 报 “cannot find package” 怎么办
根本原因不是代码写错，而是 swag 工具不读 go.mod，只按源码里的 import 语句去本地文件系统里找包。如果 github.com/gin-gonic/gin 没真正下载到模块缓存，它就扫不到。
必须先让 Go 把依赖落地：
- 确保项目已初始化模块：
go mod init example.com/api - 运行
go mod tidy—— 这步会拉取gin、swaggo等所有 import 列表中出现的包 - 再执行
swag init -g main.go，显式指定入口，避免误扫其他目录 - 若仍失败，检查
GO111MODULE=on是否生效（go env GO111MODULE看输出）
别跳过 go mod tidy，这是最常被忽略的前置动作。
@Param 注释写错导致参数不显示
swag 不解析 r.GET("/users/{id}", handler) 这种动态注册，全靠注释推断。参数类型和位置写反，文档里就直接消失。
常见错误和写法对照：
-
@Param id path int true "user ID"→ 路径参数，path关键字不能拼错，也不能写成url或uri -
@Param name query string false "user name"→ 查询参数，query是固定关键字，不是变量名 -
@Param user body models.User true "user info"→ 请求体，models.User必须是已定义结构体，且字段带json:tag（如Username string `json:"username"`） - 注释块必须紧贴 handler 函数上方，中间不能有空行，否则
swag认为不属于该函数
访问 /swagger/index.html 显示空白或 404
生成 docs/ 目录只是产出静态资源，Gin 不会自动托管它。漏掉任一环都会导致页面打不开。
三个硬性条件缺一不可：
- 在
main.go的import块中加一行：_ "example.com/api/docs"（注意下划线，且模块名必须和go.mod第一行完全一致） - 导入
github.com/swaggo/gin-swagger和github.com/swaggo/files，并 alias 成ginSwagger和swaggerFiles - 路由注册后加这行：
r.GET("/swagger/*any", ginSwagger.WrapHandler(swaggerFiles.Handler))
如果改了 go.mod 模块名但没同步更新 _ "xxx/docs"，Swagger 页面能打开但内容为空——这是最隐蔽的坑。
全局 API 注释不生效或 swagger.json 为空
swag init 生成空 docs/swagger.json，大概率是 main.go 顶部缺少必要全局注释，或格式不对。
必须存在的最小集：
-
// @title 用户服务 API—— 没有@title，整个文档不会初始化 -
// @version 1.0—— 缺少@version也会静默失败 -
// @BasePath /api/v1—— 影响所有路由前缀，不写默认为/ - 所有注释必须在
package main下方、任何函数/变量声明之前，且每行以// @开头，后面紧跟关键词，中间**不能有空格**（如//@title是错的）
生成后立刻检查 docs/swagger.json 文件大小，非零才说明解析成功；否则回看注释位置和关键词拼写。
