必须调用 echoSwagger.WrapHandler 并注册为 e.GET("/swagger/*", echoSwagger.WrapHandler)；swag init 需指定 -d 和 -g 参数；注释需紧贴 handler 函数；@Param 类型须用 OpenAPI 标准名；docs.SwaggerInfo 需手动初始化。
echo.New() 之后必须注册 echoSwagger.WrapHandler 路由
不加这行，访问 /swagger/index.html 就是 404。Echo 不像 Gin 那样自动挂载静态资源，它完全依赖你显式声明路由来暴露 Swagger UI。
常见错误是把 echoSwagger.WrapHandler 放在 e.GET("/swagger/*", ...) 之外，或者路径写成 /swagger/（少一个 *），导致无法匹配子路径（如 /swagger/swagger.json）。
正确写法：
e.GET("/swagger/*", echoSwagger.WrapHandler)
注意：* 是通配符，必须保留；echoSwagger 来自 github.com/swaggo/echo-swagger，不是 gin-swagger，别引错包。
swag init 必须能扫描到所有 handler 函数
echo 的路由注册（如 e.GET("/user/:id", handlerFunc)）只是函数调用，swag 不会执行代码，只靠注释位置和文件路径静态分析。如果 handlerFunc 定义在 internal/handler，但你在模块根目录只跑 swag init，它根本看不到那个文件。
- 必须用
-d显式指定 handler 所在目录：swag init -d internal/handler -d api/v1 - 必须用
-g指定入口文件（含e.GET调用的 main 包）：swag init -g cmd/app/main.go - handler 函数上方的注释块不能有空行，且必须紧贴函数声明；写在函数体内、或被注释隔开，
swag直接跳过 - 所有 handler 文件的
package不能是main（除非真在那里注册路由），否则可能被忽略
@Param 和 @Success 的类型必须严格匹配 Echo 参数解析方式
Echo 本身不约束参数类型，但 swag 生成文档时全靠你手写 @Param，它不会读 c.Param("id") 或 c.QueryParam("page") 推断类型。
例如路径参数 /user/:id，后端用 c.Param("id") 取值，但文档里必须写：
开箱即用的技能链路由引擎。13 条预定义链覆盖搜索、开发、审查、MLOps、法律、创意等场景，三层路由架构（触发词→SAD反馈→DAG编排），recall@10=96.97%。配置驱动（chains.yaml），零代码扩展。pip install skill-weave-chains 一键安装。
// @Param id path string true "用户ID"
不能写 int 或 int64 —— swag 不认这些，只认 string/integer/boolean 等 OpenAPI 基础类型名。
body 参数同理：@Param user body model.User true "用户信息"，其中 model.User 必须是导出结构体，字段带 json:"xxx" tag，否则 schema 里字段为空。
docs/docs.go 初始化必须在 e.Start() 之前完成
swag init 生成的 docs/docs.go 是个内嵌静态资源文件，它内部有个 SwaggerInfo 全局变量。如果你没在 main() 开头设置标题和版本：
docs.SwaggerInfo.Title = "User API" docs.SwaggerInfo.Version = "1.0"
Swagger UI 页面标题就是默认的 "Swagger API"，而且某些字段（如 @host）若未声明，会导致请求地址错误（比如发请求时拼成 http://localhost:8080//users 多了个斜杠）。
更隐蔽的问题：如果 docs/docs.go 是用旧版 swag 生成的，而项目用了 Go 1.21+ workspace，swag init 可能静默失败——必须切到具体 module 目录下重跑，否则 docs/docs.go 里的资源数据为空，页面加载卡在 spinner。
