Iris需配合swag工具、Swagger注释及iris-contrib/swagger中间件三者才能启用Swagger文档；漏任一环均导致/swagger/*any路由404或空白。
Iris 本身不内置 Swagger 文档生成能力，必须靠 swag 工具 + 注释 + iris-contrib/swagger 中间件三者配合才能跑通。漏掉任一环，访问 /swagger 都会 404 或显示空白。
怎么用 swag init 生成 docs/ 目录
swag init 是核心命令，它扫描 Go 源码里的 Swagger 注释，生成 docs/docs.go 和 JSON 文件。这步失败，后续全白搭。
- 确保项目根目录下有
main.go（或指定入口文件），且该文件里包含// @title、// @version等基础 API 信息注释 - 运行前先安装工具：
go install github.com/swaggo/swag/cmd/swag@latest（注意不是go get） - 执行：
swag init -g main.go -o ./docs，其中-o必须指向项目内一个真实可写路径，比如./docs；不能是docs/或相对路径拼错 - 生成后检查：
docs/docs.go是否存在、是否含SwaggerInfo变量、docs/swagger.json是否能用cat或浏览器打开
为什么 /swagger/*any 路由返回 404
常见原因是中间件注册顺序不对，或 swaggerFiles.Handler 没正确传入。
Skill Weave Chains — 技能链路由引擎
下载
开箱即用的技能链路由引擎。13 条预定义链覆盖搜索、开发、审查、MLOps、法律、创意等场景，三层路由架构（触发词→SAD反馈→DAG编排），recall@10=96.97%。配置驱动（chains.yaml），零代码扩展。pip install skill-weave-chains 一键安装。
- 必须在路由注册「之后」才挂载 Swagger Handler，否则 Iris 的路由匹配会跳过它
- 使用方式只推荐这一种（v12）：
app.Get("/swagger/*any", swagger.WrapHandler(swaggerFiles.Handler)) - 不要手动拼接 URL 或改
swaggerFiles.Handler的内部路径；这个 handler 已硬编码服务/swagger/下所有子路径 - 确认你 import 的是
github.com/iris-contrib/swagger/v12和github.com/iris-contrib/swagger/swaggerFiles，版本不匹配会导致 Handler 无响应
接口注释写不对，文档里就看不到这个接口
Swag 只认特定格式的注释块，且必须紧贴 HTTP 处理函数上方，中间不能插空行或其它语句。
- 每个接口至少要有：
// @Summary、// @Router、// @Tags；缺@Router就不会被收录 -
@Router格式必须是@Router /path [method]，比如@Router /user/list [get]；中括号里是小写 method，不是GET - 参数注释要写全：比如 header 认证写
// @Param Authorization header string true "Bearer token"，少true或类型写成string以外都会丢参数 - 结构体模型要导出（首字母大写），且字段带
json:tag，否则@Success 200 {object} MyResp会解析失败
开发时频繁改注释，但页面没更新
这是最常被忽略的点：Swagger 文档不是热加载的，每次改完注释都必须重新 swag init，否则浏览器看到的永远是上次生成的旧 JSON。
- 建议把
swag init加进 Makefile 或 pre-commit hook，避免手滑忘记 - 如果用了 IDE 插件（如 VS Code Swaggo 插件），确认它调用的是你本地
swag二进制，而不是某个旧版本缓存 - 浏览器可能缓存
/swagger/doc.json，可加时间戳调试：/swagger/doc.json?t=123，或禁用缓存刷新 - 注意
docs/目录是否被.gitignore忽略——它应该提交到 Git，否则 CI 环境跑不起来
真正卡住人的地方往往不是语法，而是 swag init 无声失败（比如注释格式错导致跳过整个文件）、或 swaggerFiles.Handler 因版本错位变成空 handler。遇到空白页，第一反应不是查路由，而是直接 curl /swagger/doc.json 看返回内容。
