Iris 需组合 swaggo/swag 与 iris-contrib/swagger 实现 Swagger 文档，关键在注释、生成、路由三者严格对齐；swag init 仅扫描指定 Go 文件且注释须紧贴声明、无空行；多包需用 -g 和 -d 参数；docs/docs.go 必须被引用；路由须为 /swagger/*any 并用 swagger.WrapHandler 挂载；@Param 等注解语法敏感，修改后必须重跑 swag init。
Iris 框架本身不内置 Swagger 支持，必须靠 swaggo/swag + iris-contrib/swagger 组合实现文档自动生成；关键不是“装了就能用”，而是注释、生成、路由三者严格对齐，漏一步文档就空白或 404。
swag init 生成 docs/ 目录失败或内容为空
这是最常见卡点：swag init 不读取任意位置的注释，只扫描你显式指定的 Go 文件（默认是 main.go 所在目录及子目录），且要求注释必须紧贴函数或结构体声明上方，中间不能有空行或非注释语句。
- 确保执行
swag init时当前路径是main.go所在目录（不是项目根目录也不是 controller 目录） - 检查注释是否以
// @开头，且每行都以//起始，不能混用/* */ - 若控制器分散在多个包（如
controllers/），必须加-g参数指定入口文件，并用-d显式包含路径：swag init -g main.go -d ./controllers -
docs/docs.go必须被main.go或其导入链引用，否则 Go 编译器会丢弃该文件（Iris 的swaggerFiles.Handler依赖它）
访问 /swagger/index.html 报 404 或 JSON 加载失败
根本原因通常是路由注册方式和静态资源路径不匹配。Iris 默认不自动托管 docs/ 下的文件，必须用 swagger.WrapHandler 或 swagger.CustomWrapHandler 显式挂载，且 URL 路径要与前端 JS 请求的 doc.json 地址一致。
- 不要手动把
docs/复制到public/或assets/—— Iris 的 swagger 中间件是 embed 方式加载，直接读docs/docs.go - 路由必须注册为
app.Get("/swagger/*any", ...)，不能写成/swagger或/swagger/（缺少通配符会导致子路径 404） - 如果用了
swagger.CustomWrapHandler，config.URL必须指向实际可访问的doc.json地址，例如"http://localhost:8080/swagger/doc.json"，而不是本地文件路径 - 确认没有全局中间件（如 JWT 鉴权、CORS）拦截了
/swagger/*any路由——Swagger UI 页面和 doc.json 都需免鉴权访问
@Summary/@Param 等注解不生效或参数丢失
Iris 不解析注解，全靠 swag 命令行工具静态分析源码。它对注解语法极其敏感，且不支持自动推导参数类型或绑定逻辑。
-
@Param必须显式声明in类型（query、path、header、body），不能只写名字和描述 - 使用
@Param name query string true "用户名"时，string是数据类型，true表示 required，顺序不能错 -
@Success和@Failure的响应体若为结构体，需确保该结构体已定义且可被swag扫描到（不能是未导出字段或跨 module 未 import） - 避免在 handler 函数里嵌套闭包或匿名函数——
swag只解析顶层函数，内部函数注释会被忽略
最容易被忽略的是：每次修改注解后必须重新运行 swag init，Go 代码热重载不会触发文档更新；而 docs/docs.go 一旦生成，就成为静态资源，哪怕注释删了，旧文档仍会显示——务必养成“改注释 → 跑命令 → 删旧 docs（可选）→ 重启服务”的习惯。
