根本原因是swag不解析go.mod依赖路径，仅扫描源码import语句；需先go mod tidy下载依赖（如github.com/gin-gonic/gin），再执行swag init -g main.go指定入口。
为什么直接用 swag init 会报错 “cannot find package”
因为 swag 工具不解析 go.mod 的依赖路径，而是直接扫描源码中的 import 语句——如果 Gin 的导入路径写成 "github.com/gin-gonic/gin"（标准写法），但本地 GOPATH 或模块缓存里没这个包，swag init 就会失败。不是代码问题，是工具链没加载依赖。
实操建议：
- 先确保项目已初始化模块：
go mod init example.com/api - 运行
go mod tidy下载所有依赖，包括github.com/gin-gonic/gin - 再执行
swag init -g main.go，指定入口文件避免扫描错目录 - 若仍报错，临时加
-parseVendor（仅当 vendor 存在时）或检查GO111MODULE=on是否生效
如何让 Swagger 正确识别 Gin 的路由和参数
Gin 本身不暴露结构化路由元信息，swag 只能靠注释推断。它不解析 r.GET("/user/:id", handler) 这类动态调用，必须手动补全注释块。
关键点：
立即学习“go语言免费学习笔记（深入）”；
-
@Summary和@Description必须紧贴 handler 函数上方（不能隔空行） - 路径参数要用
@Param id path int true "user ID"显式声明，path类型不能省略 - Query 参数写成
@Param name query string false "user name"，query是固定关键字 - 请求体必须标注
@Param request body models.User true "user info"，且models.User类型需有 JSON tag（如json:"name"）
示例 handler 注释：
// @Summary Get user by ID
// @Description get user from database by ID
// @ID get-user-by-id
// @Produce json
// @Param id path int true "user ID"
// @Success 200 {object} models.User
// @Router /users/{id} [get]
func GetUser(c *gin.Context) {
// ...
}
为什么访问 /swagger/index.html 显示空白或 404
生成的 docs/ 目录只是静态资源，Gin 不会自动托管它。常见错误是只跑 swag init 却没挂载路由。
正确做法：
- 导入生成的 docs 包：
import _ "example.com/api/docs"（注意下划线，触发 init） - 在 router 初始化后加：
r.GET("/swagger/*any", ginSwagger.WrapHandler(swaggerFiles.Handler)) - 确认
swag init后生成了docs/docs.go文件；没有说明注释格式或路径有误 - 如果用 Go 1.21+，
swaggerFiles.Handler默认启用嵌入文件系统，无需额外http.Dir配置
如何支持 JWT 认证并在 Swagger 中填 Bearer Token
Swagger UI 默认不带认证头，需显式声明安全方案并绑定到接口。
操作步骤：
- 在
main.go的注释顶部加全局安全定义：@SecurityDefinitions.apikey ApiKeyAuth - 补充 scheme：
@SecurityDefinitions.apikey.TokenUrl https://example.com/login - 在需要鉴权的接口上加：
@Security ApiKeyAuth - 确保 handler 函数注释中包含
@Header 200 {string} X-Auth-Token "JWT token"（可选，用于示例）
生成后，Swagger UI 右上角会出现 “Authorize” 按钮，输入 Bearer xxx 即可透传到请求头。
swag init，且不要依赖 IDE 自动刷新 —— 它不会触发 docs 包重建。 
