Go语言Echo框架Swagger文档生成-Golang-PHP中文网

swag init 找不到 handler 函数注释是因为 echo 路由使用变量引用或匿名函数，而 swag 仅扫描具名函数；需确保 handler 为导出的具名函数、注释紧贴声明、路径匹配且静态路由手动注册。

go语言echo框架swagger文档生成

因为 Echo 的路由注册方式（如 e.GET("/users", handler)）不直接暴露函数名，swag 默认只扫描包级函数和方法，而不会解析变量赋值或闭包。如果你把 handler 写成匿名函数或通过变量间接引用，swag init 就会跳过它。

实操建议：

Echo框架 5.1.0

Echo框架 5.1.0 版本源码包下载，适合关注 RealIP 行为变化、StartConfig.Listener、NewDefaultFS 和观测性中间件入口的开发团队。

下载

所有 handler 必须是具名函数（例如 func GetUser(c echo.Context) error），不能是 func(c echo.Context) error { ... }
确保 handler 函数在 swag init 扫描的包路径内（默认当前目录，可用 -g 指定入口 Go 文件）
注释必须紧贴函数声明上方，且以 // @Summary 开头，中间不能有空行
如果使用子路由组（g := e.Group("/api")），注释仍要写在最终 handler 函数上，而不是 group 定义处

swag 不解析运行时代码逻辑，它只认注释里的 OpenAPI 字段声明。即使你在 handler 里调用了 c.Param("id")，若没在注释中显式写 // @Param id path string true "user ID"，Swagger UI 就不会显示该参数。

实操建议：

路径参数（/users/{id}）必须用 @Param 明确标注 path 类型，并与路由定义中的占位符名称一致
查询参数（?page=1&limit=20）用 @Param 标为 query 类型；表单字段（c.FormValue()）标为 formData；请求体（c.Bind()）靠 @Success 或 @Failure 中的 schema 推导结构
避免混用：不要在注释里写 id，但在路由里写 /users/:uid —— 名称必须完全匹配

这是因为 Echo 不自动挂载 Swagger UI 静态资源，你得手动注册路由并启用 docs.ServeSwagger 和 docs.NewHandler。仅运行 swag init 只生成描述文件，不接入框架。

实操建议：

在 main.go 或启动文件中 import "github.com/swaggo/files" 和 "github.com/swaggo/http-swagger"（注意不是 gin-swagger）
添加路由：e.GET("/swagger/*any", echo.WrapHandler(httpSwagger.Handler(httpSwagger.URL("/swagger/doc.json"))))
确保 docs/doc.go 已生成且未被 gitignore 忽略；若用 -o 指定了输出目录，要同步更新 httpSwagger.URL() 中的路径
开发时可加 httpSwagger.DeepLinking(true) 支持 URL 锚点跳转