Iris 默认不带 Swagger 支持，因其设计轻量、不自动扫描路由或注释；需用 swag CLI 生成 docs 包，再通过 StaticWeb 或 HandleDir 暴露 /swagger/ 路由，并确保 swagger.json 可访问。

为什么 Iris 默认不带 Swagger 支持？ Iris 是轻量、高性能的 Go Web 框架，设计上不内置 OpenAPI/Swagger 文档生成逻辑——它不自动扫描路由或结构体注释。这意味着你不能像 Spring Boot 那样加个 @EnableSwagger2 就完事。文档生成必须手动桥接：用第三方工具（如 swag）生成 docs 包，再由 Iris 加载并暴露 /swagger/* 路由。

常见错误是直接 import github.com/swaggo/http-swagger 后调用 http-swagger.WrapHandler，却忘了初始化 docs 包，结果访问 /swagger/index.html 时 404 或白屏。

Iris框架 12.2.5

Iris框架 12.2.5 版本源码包下载，适合需要 MVC Singleton 控制器、依赖注入字段控制和 debug 错误日志改进的开发者。

下载

怎么用 swag CLI 生成 docs 包？ swag 是最主流的 Go OpenAPI 生成工具，需配合注释 + 命令行使用：

• 在 main.go 或 API 入口文件顶部添加通用注释，例如：

  // @title User API
  // @version 1.0
  // @description This is a sample user management API.
  // @host localhost:8080
  // @BasePath /api/v1

• 每个 HTTP 处理函数上方加 @Summary、@Tags、@Param、@Success 等注释，例如：

  // @Summary Get user by ID
  // @Tags users
  // @Accept json
  // @Produce json
  // @Param id path int true "User ID"
  // @Success 200 {object} models.User
  // @Router /users/{id} [get]

• 确保项目根目录下有 go.mod，然后执行：

  swag init -g main.go -o ./docs

  （-o 指定输出目录，默认就是 ./docs）
• 成功后会生成 docs/docs.go、docs/swagger.json 等文件；该 docs 包会被 Iris 作为静态资源加载源

如何在 Iris 中注册 Swagger UI 路由？ 关键不是“接入 Swagger”，而是“把 docs 包里的静态资源和 JSON 暴露给前端”。Iris 不提供开箱即用的中间件，需手动注册两个部分：

• 用 app.StaticWeb("/swagger", "./docs") 暴露整个 docs 目录（含 index.html、JS/CSS）
• 但注意：默认 StaticWeb 不支持路径重写，而 Swagger UI 会请求 /swagger/swagger.json，实际文件却是 ./docs/swagger.json —— 所以要确保 ./docs 下有完整可访问的资源树
• 更稳妥的做法是显式挂载 JSON 文件：

  app.Get("/swagger/swagger.json", func(ctx iris.Context) {
      ctx.ServeFile("./docs/swagger.json", false)
  })

• 如果用的是 Iris v12+，推荐改用 app.HandleDir 并指定 index：

  app.HandleDir("/swagger", iris.Dir("./docs"), iris.DirOptions{
      IndexName: "index.html",
  })

常见报错和兼容性注意点

多数问题出在路径映射、注释格式或版本错配：

• undefined: docs.SwaggerInfo：说明 swag init 没成功运行，或 docs/docs.go 未被 go build 扫描到（检查是否在 main 包下 import "./docs"）
• Swagger UI 显示 “Failed to load spec.”：检查浏览器 Network 面板，看 /swagger/swagger.json 是否返回 404 或 406；常见原因是 StaticWeb 路径没对齐，或 JSON 文件权限/编码异常（确保 UTF-8 无 BOM）
• Iris v12+ 的 HandleDir 默认禁用目录遍历，若需支持子路径（如 /swagger/swagger-ui-bundle.js），需显式开启：EnableDirectoryList: true
• swag CLI 版本要与 github.com/swaggo/swag Go 包版本一致（建议都用 v1.16.x），否则 docs/docs.go 里生成的 struct 字段可能不匹配

Iris 接入 Swagger 的本质是「静态资源托管 + OpenAPI 规范文件暴露」，没有魔法，只有路径对得上、注释写得准、包导入不遗漏——最容易被跳过的，是 swag init 后忘记重新构建二进制，或者把 docs 目录放错位置导致运行时找不到文件。