swag init扫不到Echo路由,根本原因是未显式指定路径、入口和package:必须用-d指定handler目录(如internal/router)、-g指定入口文件(如cmd/app/main.go),且handler文件不能是package main,须有合法package声明和UTF-8无BOM注释。

swag init 扫不到 Echo 路由?路径、入口、package 必须对齐
执行 swag init 后 docs/swagger.json 里 "paths":{},Swagger UI 空白——根本不是 swag 坏了,而是它压根没看到你的 echo.GET() 或 echo.POST() 调用。
swag 默认只扫描当前目录及子目录下属于同一 Go module 的 .go 文件,且要求:
-
-d显式指定 handler 所在目录,比如swag init -d internal/handler -d pkg/api;Echo 路由通常分散在internal/router或pkg/endpoint,不加-d就等于没扫 -
-g必须指定入口文件(如cmd/app/main.go),否则跨包注册的e.GET("/user", handler.GetUser)会被跳过 - 被扫描的文件不能是
package main(除非它直接写了e := echo.New()和路由注册),推荐统一用package router或package endpoint - 所有文件必须有合法
package xxx声明,任一文件语法错误(比如少个}),整个包都会被静默跳过
@Param 和 @Success 写错类型?swag 不走 Go 编译器那套
报错 cannot find type definition for "uuid.UUID" 或响应 schema 显示空 object,不是你 struct 写得不对,而是 swag 类型解析器根本不认 Go 的类型系统。
它只识别两类东西:基础类型名(string、int、bool、float64)和已用 // @Model 显式声明过的 struct。
- 路径/查询/请求头参数一律写
string:@Param id path string true "用户ID"✅,别写int64或uuid.UUID❌ - 请求体(
in: body)必须指向一个已定义 struct,且该 struct 上方要有// @Model注释 -
@Success 200 {object} model.UserResponse中的UserResponse必须导出(首字母大写),每个字段必须带json:tag,漏一个 tag,字段就消失 - 数组参数不能简写:
@Param ids query array true "ID列表" collectionFormat:multi items.type:string✅,type: []string❌
中文乱码、字段全空、显示 “object”?三个硬性条件缺一不可
文档加载后中文变 \u4f60\u597d,或点开响应 schema 一片空白——这不是配置问题,是代码层面没满足 swag 的硬性约束。
Echo框架 5.1.0 版本源码包下载,适合关注 RealIP 行为变化、StartConfig.Listener、NewDefaultFS 和观测性中间件入口的开发团队。
- 所有注释(
@Param、@Success、// @Model)必须保存为 UTF-8 编码,且禁用 BOM(VS Code 默认可能带 BOM,需手动转) -
@Success引用的 struct 必须导出(首字母大写),例如UserResponse,不能是userResponse - struct 每个字段都必须有
json:tag,例如Name string;哪怕只漏一个,整个字段就不会出现在 schema 中json:"name"
集成 Echo 时如何让 /swagger/*any 正常工作?
注册路由后访问 /swagger/index.html 报 404 或空白页,大概率是静态资源没挂对。
swag 生成的 docs 包必须被显式导入,且 Echo 的 StaticFS 配置要匹配 swaggo/files 的路径结构:
- 确保
go mod tidy已拉取github.com/swaggo/files和github.com/swaggo/echo-swagger - 在入口文件 import
_ "your-project-path/docs"(注意是 underscore 导入,触发 docs 包 init) - 路由注册写法必须是:
e.GET("/swagger/*any", echoSwagger.WrapHandler(swaggerFiles.Handler)),*any不能少,否则子路径(如/swagger/swagger.css)404 - 不要用
e.Static直接挂载docs目录,swaggo/files 是嵌入式 FS,路径映射逻辑和普通静态文件不同
最易忽略的是 underscore 导入和 *any 通配符——少一个,整个 Swagger UI 就起不来。










