swagger注解必须写在handler函数正上方且同module内，显式注册、导出函数、补全@param/@success、为struct添加@schema，挂载ui需直连e实例并配置静态资源。
Swagger 注解必须写在 handler 函数上方，且不能跨包引用
Go 里 Swagger 文档生成依赖 swag init 扫描源码中的注释，它只识别当前 module 下、被直接 import 的 handler 函数上的注释块。如果你把路由 handler 放在 internal/handler 包里，而 main.go 在根目录，swag init 默认能扫到；但若 handler 定义在另一个独立 module（比如 github.com/yourname/api），即使 import 了，swag 也不会解析——它不走 go list 或模块依赖图，只做文件级静态扫描。
实操建议：
- 所有带
// @Summary、// @Success等注解的函数，必须与swag init执行路径下的main.go处于同一 module，且被至少一个echo.GET/echo.POST显式注册（哪怕只是临时注册） - 避免在 interface 或未导出函数上写 Swagger 注解，
swag只处理首字母大写的导出函数 - 注解块必须紧贴函数声明正上方，中间不能有空行；否则会被忽略
echo.Context 参数无法直接用于 Swagger 类型推导
Swagger 生成器不会解析 echo.Context 的实际用法，比如你调用 c.Param("id") 或 c.QueryParam("page")，它不知道这是 path 参数还是 query 参数——这些信息必须显式通过注解声明。
常见错误现象：接口文档里 missing Parameters、200 响应体显示 object{}、或根本没生成请求参数字段。
实操建议：
- 每个 HTTP 方法对应 handler 必须手动补全
// @Param（path / query / header / body）和// @Success（含schema引用） - body 参数需配合 struct tag 使用：
json:"name" example:"test"，否则swag无法推断字段示例值 - 如果用
c.Bind()解析 JSON body，务必让 struct 导出，并在注解中写// @Param request body models.User true "user info"
嵌套 struct 和自定义类型需要显式添加 // @Schema
当你返回的响应结构体包含嵌套 struct、指针字段、map 或自定义类型（如 type UserID int64），swag 默认无法生成完整 schema，容易出现 undefined 或字段丢失。
使用场景：用户详情接口返回 User{Profile: &Profile{Name: "A"}, Roles: []string{"admin"}}，文档里 Profile 显示为 object{}，Roles 显示为 array[]。
实操建议：
- 为每个参与序列化的 struct 添加
// @Schema注释块（哪怕空着），并确保 struct 字段全部导出、带jsontag - 对别名类型（如
type Status string），加// @Schema enum="active,inactive"或// @Schema example="active"明确语义 - 避免在 schema struct 中嵌入未导出字段或匿名 struct，否则
swag会跳过整个字段
启动 Swagger UI 需手动挂载，且路径不能与 echo.Group 冲突
Swagger UI 是静态资源，Echo 不会自动托管。很多人直接写 echo.Static("/swagger", "./docs")，结果 404——因为 ./docs 是 swag init 输出的目录，但 Echo 的 Static 默认不支持 index.html 自动匹配，且若你用了 echo.Group("/api")，再挂载 /swagger 就得注意路由优先级。
实操建议：
- 用
echo.File("/swagger/index.html", "./docs/index.html")启动单页入口，再配echo.Static("/swagger/swagger.yaml", "./docs/swagger.yaml")和echo.Static("/swagger/swagger.json", "./docs/swagger.json") - 不要把 Swagger 路由挂在
Group下（如g := e.Group("/api"); g.File(...)），否则访问/api/swagger/index.html会失败；应直接挂到e实例上 - 开发时可加
// @host localhost:8080和// @schemes http，避免 UI 默认尝试 https 请求失败
最易被忽略的是注解与代码结构的耦合性：改了一个 struct 字段名，忘了同步更新 // @Schema 里的 example 或 description，文档就立刻失真；swag init 不报错，但生成结果不可信。每次提交前最好本地跑一次 swag init -g main.go 并打开 UI 快速核对关键接口。
golang免费学习笔记（深入）：立即使用
在学习笔记中，你将探索golang的核心概念和高级技巧！
