根本原因是docs/docs.go未被导入触发init()，导致文档数据未注册；必须在main.go中添加_blank import_ "your-module-name/docs"，且模块名须与go.mod首行完全一致。
swag init 为什么生成 docs/ 却访问 /swagger/index.html 404
根本原因不是路由没配，而是 docs/docs.go 没被导入——它里面的 init() 函数负责把文档数据注册进内存，不触发就等于没文档。
必须在 main.go 的 import 块里加这行：
_ "your-module-name/docs"
注意：your-module-name 必须和 go.mod 第一行的模块名完全一致。写成 _ "./docs" 或 _ "docs" 都无效；如果项目用了 Go Modules，模块名带版本（如 example.com/api/v2），这里也得写全。
-
swag init成功后检查docs/swagger.json是否有内容，空文件说明注释格式错（比如@Param后少空格、换行不对） - 执行
swag init时默认只扫描当前目录及子目录，handler 分散在handlers/下要加-d ./ - 如果用
go.work多模块，swag init必须在主模块根目录运行，否则找不到跨模块的 handler 注释
@Param 的 type 和 in 写反会导致参数不显示
@Param 的三个关键字段是 name、in、type，顺序错或值错都会让参数在 UI 里消失或报错。
常见错误写法：
-
@Param id query int true "ID"→ 实际路径是/users/{id}，但写成了query，应为path -
@Param user body User true "用户"→User是结构体，必须写全包名，如models.User，否则解析失败 -
@Param file formData file true "头像"→file不是合法 type，得写string，再配合@Accept multipart/form-data
正确示例：
// @Param username query string true "用户名" // @Param id path int true "用户ID" // @Param user body models.User true "用户对象" // @Accept json
router.GET("/swagger/*any", ...) 为什么只显示 JSON 不出 UI
直接 router.Static("/swagger", "./docs") 只暴露静态文件，没加载 Swagger UI 的前端逻辑，所以打开是 raw JSON 或 404。
必须用 gin-swagger 提供的封装 handler：
import swaggerFiles "github.com/swaggo/files"
import ginSwagger "github.com/swaggo/gin-swagger"
// 注册路由
router.GET("/swagger/*any", ginSwagger.WrapHandler(swaggerFiles.Handler))
注意：github.com/swaggo/files 是包路径，导入时 alias 成 swaggerFiles 是惯例，但包本身不叫 swaggerFiles ——写错 alias 不影响，但路径写错就 import 失败。
- 如果启动后访问
/swagger/index.html是空白页，先检查浏览器控制台是否报swagger-ui-bundle.js404，大概率是swaggerFiles.Handler没生效 - 不要手动复制
index.html到docs/下，gin-swagger内部已内置完整 UI 资源
swag 命令找不到或 swag -v 报 command not found
Go 1.16+ 强制要求用 go install 安装 CLI 工具，go get 不再把二进制放到 $GOPATH/bin。
正确安装方式：
go install github.com/swaggo/swag/cmd/swag@latest
然后确认 $GOPATH/bin 在 $PATH 中：
- Linux/macOS：运行
echo $PATH看是否含$GOPATH/bin，没有就加到~/.bashrc或~/.zshrc - Windows：检查系统环境变量
PATH是否包含%GOPATH%\bin
装完立刻验证：
swag -v
输出类似 swag version v1.8.10 才算成功。如果还报错，别重试，先查 $GOPATH/bin 下有没有 swag 或 swag.exe 文件。
最易忽略的是：swag init 必须在包含 main.go 的模块根目录执行，否则它找不到全局注释，生成的 docs/docs.go 里全是空结构体。
