swag init 找不到 handler 函数注释是因为 Echo 路由使用变量引用或匿名函数，而 swag 仅扫描具名函数；需确保 handler 为导出的具名函数、注释紧贴声明、路径匹配且静态路由手动注册。
为什么 swag init 找不到 handler 函数注释？
因为 Echo 的路由注册方式（如 e.GET("/users", handler)）不直接暴露函数名，swag 默认只扫描包级函数和方法，而不会解析变量赋值或闭包。如果你把 handler 写成匿名函数或通过变量间接引用，swag init 就会跳过它。
实操建议：
立即学习“go语言免费学习笔记（深入）”；
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 定义处
如何让 Swagger 正确识别 Echo 的 c.Param() 和 c.QueryParam()？
swag 不解析运行时代码逻辑，它只认注释里的 OpenAPI 字段声明。即使你在 handler 里调用了 c.Param("id")，若没在注释中显式写 // @Param id path string true "user ID"，Swagger UI 就不会显示该参数。
实操建议：
立即学习“go语言免费学习笔记（深入）”；
- 路径参数（
/users/{id}）必须用@Param明确标注path类型，并与路由定义中的占位符名称一致 - 查询参数（
?page=1&limit=20）用@Param标为query类型；表单字段（c.FormValue()）标为formData；请求体（c.Bind()）靠@Success或@Failure中的schema推导结构 - 避免混用：不要在注释里写
id，但在路由里写/users/:uid—— 名称必须完全匹配
生成的 docs/docs.go 没生效，访问 /swagger 404？
这是因为 Echo 不自动挂载 Swagger UI 静态资源，你得手动注册路由并启用 docs.ServeSwagger 和 docs.NewHandler。仅运行 swag init 只生成描述文件，不接入框架。
实操建议：
立即学习“go语言免费学习笔记（深入）”；
- 在
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 锚点跳转
返回结构体嵌套、指针字段或 interface{} 导致 Swagger 类型丢失？
swag 依赖 AST 分析结构体定义，遇到 *User、map[string]interface{} 或未导出字段（小写开头）时，无法推断实际类型，Swagger 中就显示成 object 或直接空缺。
实操建议：
立即学习“go语言免费学习笔记（深入）”；
- 响应结构体字段必须首字母大写（导出），且避免用
interface{}；改用具体 struct 或定义// @Schema注释说明 - 对指针字段（如
Name *string），在注释中用// @Property x-nullable true显式标记可空性 - 嵌套结构体需确保其所在包被
swag init扫描到（跨包时用-p添加包路径） - 若用
json:",omitempty"，不影响类型推导，但需注意字段是否真会被序列化
