Echo集成Swagger必须用swag静态解析+echo-swagger挂载，不能运行时反射或手写YAML；需正确指定扫描路径、包名、UTF-8编码、@Model注释及v2版导入路径与路由写法。
Echo 框架集成 Swagger 必须用 swag 静态解析注释 + echo-swagger 挂载路由，不能靠运行时反射或手写 YAML —— 否则文档和接口必然脱节。
swag init 扫不到 Echo 的 handler 函数？检查扫描路径和 package 声明
swag 默认只扫当前目录下 package main 或同 module 内的 .go 文件，而 Echo 项目常把路由注册放在 internal/router 或 pkg/api 下，这些文件若没被显式包含，swag init 就会跳过。
- 执行
swag init -d internal/router -d pkg/api -g cmd/app/main.go，强制指定 handler 所在路径和入口文件 - 确保所有含
// @Summary等注释的 handler 文件顶部是合法package router（不能是package main，除非它真注册了e.GET()） - 文件里不能有语法错误（比如少
}、未闭合字符串），否则整个文件被 AST 解析器丢弃 - 若用了
go:embed或多模块结构，必须加-d，否则swag根本不进子模块目录
注册 /swagger/*any 路由时 import 路径和函数名容易写错
echo-swagger v2 的导入路径和调用方式与旧版完全不同，抄老教程会直接编译失败。
Skill Weave Chains — 技能链路由引擎
下载
开箱即用的技能链路由引擎。13 条预定义链覆盖搜索、开发、审查、MLOps、法律、创意等场景，三层路由架构（触发词→SAD反馈→DAG编排），recall@10=96.97%。配置驱动（chains.yaml），零代码扩展。pip install skill-weave-chains 一键安装。
- 必须用
github.com/swaggo/echo-swagger/v2，不是github.com/swaggo/echo-swagger - 必须用
github.com/swaggo/files/v2，不是github.com/swaggo/files - 挂载写法是：
e.GET("/swagger/*any", echoSwagger.WrapHandler(swaggerFiles.Handler))，不是echoSwagger.Handler或docs.Handler - 路径必须带通配符
/swagger/*any，写成/swagger/或/docs/都无法加载静态资源
@Param 和 @Success 注释里类型写法受限，别想当然套 Go 类型
swag 不走 Go 类型系统，它只认基础类型名和显式声明过的 struct，写错就显示 object 或报 cannot find type definition。
- 路径/查询/请求头参数只能写
string、int、bool、float64—— 别写int64、uuid.UUID、time.Time - 请求体（
in: body）必须指向一个已定义的 struct，且该 struct 上方需有// @Model注释 -
@Success 200 {object} UserResponse中的UserResponse必须首字母大写（导出）、字段带json:tag，否则字段全空 - 数组查询参数要写全：
@Param ids query array true "ID列表" collectionFormat:multi items.type:string，不能简写为type: []string
中文注释乱码、字段不展开、文档空白？先确认三件事
这三个硬性条件只要漏一个，Swagger UI 就会表现异常：首页能打开但没接口、响应体只显示 object、字段名全空、中文变问号。
- 所有注释文件必须保存为 UTF-8 编码（Windows 记事本默认 ANSI，易踩坑）
- 全局注释块（含
@title、@version）必须在同一个文件中，且@title和@version缺一不可 -
@Model注释必须紧贴 struct 定义上方，中间不能有空行或其它注释干扰
最常被忽略的是 @Model 和 UTF-8 编码 —— 这两个点不卡死，其他都白调。
