Echo路由不自动生成Swagger文档，因swag仅静态扫描含@Router等注释的具名handler函数，不解析e.GET等运行时路由语句；需确保注释紧贴函数、路径格式匹配（如:id→{id}）、结构体字段可导出且带json tag，并用echo-swagger.WrapHandler挂载/swagger/*any路由。
Echo 路由本身不生成 Swagger 文档，必须配合 swag 工具 + 正确注释 + 手动挂载路由才能在 /swagger/*any 下看到可交互文档。
为什么 Echo 的 e.GET 等路由不会自动出现在 Swagger UI 里
Swag 不解析 Echo 的路由注册语句（如 e.GET("/user/:id", handler)），它只扫描 Go 源文件中被注释标记的 handler 函数。即使你写了 e.GET("/users", getUsers)，若 getUsers 函数上方没有 // @Router /users [get] 这类注释，swag init 就完全看不到这个接口。
- Swag 是静态源码分析工具，不是运行时中间件，不 hook Echo 的路由树
- 所有
@Router注释里的路径必须和实际 Echo 路由一致（比如 Echo 用/user/:id，注释就得写@Router /user/{id} [get]，注意:id→{id}） - 如果 handler 是闭包（如
e.GET("/ping", func(c echo.Context) error {...})），无法加注释 → 必须提取为具名函数
swag init 扫不到 Echo 接口的常见原因
执行 swag init 后 docs/swagger.json 中 "paths" 为空，大概率是扫描范围或注释格式出错。
Skill Weave Chains — 技能链路由引擎
下载
开箱即用的技能链路由引擎。13 条预定义链覆盖搜索、开发、审查、MLOps、法律、创意等场景，三层路由架构（触发词→SAD反馈→DAG编排），recall@10=96.97%。配置驱动（chains.yaml），零代码扩展。pip install skill-weave-chains 一键安装。
- 没指定入口文件：
swag init -g cmd/myapp/main.go必须显式给出含echo.New()和路由注册的 main 文件 - handler 分散在
internal/handler或pkg/api？得加-d internal/handler -d pkg/api多次指定目录 - 注释没紧贴函数声明：
func getUsers(c echo.Context) error { ... }上方不能有空行，且必须是连续的// @xxx块 - 用了未导出结构体（如
type user struct）或字段没json:tag →@Success 200 {object} user会失败或显示空 schema
如何让 /swagger/*any 正确加载 Echo 的文档
不同于 Gin，Echo 没有官方 echo-swagger v2 兼容包，需用社区维护的 github.com/swaggo/echo-swagger（注意不是 gin-swagger）。
- 安装：
go get github.com/swaggo/echo-swagger - 导入：
import "github.com/swaggo/echo-swagger"（不是v2后缀） - 挂载路由：
e.GET("/swagger/*any", echoSwagger.WrapHandler)—— 路径必须带/*any，不能写成/swagger/或/docs/ - 确保
docs/docs.go已生成且已 import（如import _ "./docs"），否则WrapHandler会 panic
路径参数、查询参数、请求体怎么写才被正确识别
Swag 对参数类型极其敏感，Echo 路由里用 :id，注释里必须转成 OpenAPI 格式 {id}，且类型只能是基础类型。
- 路径参数：
// @Param id path int true "用户ID"✅（不能写int64或uuid.UUID） - 查询参数：
// @Param name query string false "用户名"✅（collectionFormat: multi才支持?ids=1&ids=2） - 请求体：
// @Param user body model.User true "用户信息"，且model.User上方必须有// @Model注释 - 响应数组：
// @Success 200 {array} model.User✅（不是{object} []model.User）
最易忽略的一点：所有结构体字段必须首字母大写 + 带 json:"field_name" tag，否则 Swagger UI 里字段名为空、类型显示为 object。
