iris-go集成swagger必须严格匹配版本：iris v12需用iris-contrib/swagger/v12，swag需v1.10.5，注解须写在handler上方且含@summary/@description，每次修改后执行swag init -g main.go，路由注册须在中间件前，/swagger/doc.json可访问是关键验证点。
直接集成可行，但必须严格匹配 iris-contrib/swagger 的版本与 Iris 主版本，否则 swag init 生成的文档无法被正确加载，访问 /swagger/index.html 会白屏或报 404。
确认 Iris 和 swagger 版本是否兼容
Iris v12 必须用 github.com/iris-contrib/swagger/v12，不能用 v13 或无版本后缀的 swagger。v12 以下版本（如 v11）需对应 v11 分支。常见翻车点：
-
go get github.com/iris-contrib/swagger→ 默认拉取最新版，大概率不兼容 - 误装
swaggo/swagv1.10+ 后，swag init -g main.go生成的docs/docs.go里 import 路径含v2，而iris-contrib/swagger/v12期望的是v12路径 - 运行时 panic：`cannot find package "github.com/iris-contrib/swagger/v12/swaggerFiles"`，说明 Go module 解析失败
正确做法：
go env -w GOPROXY=https://goproxy.cn,direct go get github.com/swaggo/swag/cmd/swag@v1.10.5 go get github.com/iris-contrib/swagger/v12@v12.2.0-alpha
注释写法和 swag init 执行时机
Swagger 注解必须写在 handler 函数上方（不是 struct 方法内部），且 @Router 路径要与实际注册路由一致。Iris 不支持自动扫描 controller 目录，所有注解必须手动覆盖到每个 handler。
-
@Summary和@Description必须存在，缺一不可，否则该接口不会出现在文档中 -
@Accept和@Produce值写成json是错的，应为application/json - 每次修改注释后，必须重新执行
swag init -g main.go，否则前端看到的仍是旧文档 -
-g main.go中的main.go是入口文件路径，若项目结构是cmd/app/main.go，就得写全路径
示例（正确）：
// @Summary 获取用户列表
// @Description 返回全部用户信息
// @Tags 用户
// @Accept application/json
// @Produce application/json
// @Success 200 {array} models.User
// @Router /user/list [get]
func getUserList(ctx iris.Context) {
ctx.JSON([]models.User{{Name: "a", Age: 20}})
}
路由注册和中间件顺序不能错
Iris 的 swagger.WrapHandler 是一个标准 handler，必须注册在所有路由之前（或至少在 /swagger/*any 路径前），否则可能被其他中间件拦截（比如 JWT 鉴权中间件会拒绝未带 token 的请求）。
- 错误写法：
app.Use(authMiddleware)放在app.Get("/swagger/*any", ...)之前 → 访问 Swagger 页面提示 401 - 正确顺序：先挂载 Swagger 路由，再挂载业务路由和全局中间件
- 如果用了
config.URL指向远程doc.json，确保该 URL 可被浏览器直连，且响应头含Content-Type: application/json - 本地嵌入模式下，
swaggerFiles.Handler依赖docs/docs.go文件，该文件必须由swag init生成，且不能被go:embed或其他方式覆盖
启动后访问不到 /swagger/index.html 怎么排查
最常被忽略的是静态资源路径映射问题 —— Iris 默认不自动 serve swagger-ui 的 HTML/CSS/JS，它靠 swaggerFiles.Handler 内部的 http.FileServer 提供，而这个 server 依赖 docs 包已编译进二进制。
- 检查
docs/docs.go是否存在、是否被go build编译进去（运行go list -f '{{.Deps}}' ./... | grep docs确认） - 浏览器打开
/swagger/doc.json，看能否返回 JSON；如果 404，说明docs包没生效或路径注册失败 - 控制台报错
Failed to load API definition，大概率是doc.json返回了 HTML（比如 Nginx 重定向到了首页）或 CORS 阻断 - 若用 Docker 部署，确认镜像内包含
docs包（Go 构建阶段不能用--ldflags="-s -w"过度裁剪）
真正卡住的地方往往不在配置本身，而在 swag init 是否成功生成了可被导入的 docs 包，以及这个包有没有被 Iris 正确识别并注入到 swaggerFiles.Handler 中 —— 这个链路没有日志输出，只能靠 /swagger/doc.json 这个端点来验证起点是否成立。
