Echo框架整合Swagger自动文档-Golang-PHP中文网

swag init 扫不到 echo handler 的根本原因是默认只扫描当前目录下 package main 或同 module 内的文件，而 echo handler 多位于 internal/handler、api 等非 main 包中，需用 -d 显式指定路径并用 -g 指向 main 入口文件。

echo框架整合swagger自动文档

swag init 扫不到 Echo handler 怎么办

根本原因不是 Echo 特殊，而是 swag 默认只扫描当前目录下 package main 或同 module 内的文件，而 Echo 的路由注册通常分散在 internal/handler、api/ 等非 main 包里。不显式指定路径，swag init 就会“看不见”你的 handler。

必须用 -d 显式列出所有含 handler 的目录，且用 -g 指向含 main() 的入口文件：

swag init -d internal/handler -d api -g cmd/main.go -o ./docs
确保这些目录下的 .go 文件都有合法 package xxx（不能是 package main，除非它真写了 e.GET()）
handler 函数必须导出（首字母大写），且注释块紧贴函数声明上方，中间不能有空行

Echo 注册 Swagger UI 路由的正确写法

和 Gin 不同，Echo 没有封装好的 ginSwagger.WrapHandler，得手动托管静态资源 + 注册 HTML 入口。常见错误是只挂了 /swagger/*any 却没处理 /swagger/index.html 重定向，导致页面白屏或 404。

正确做法分两步：

调用 e.Static("/swagger", "./docs")，把生成的 docs/ 目录作为静态资源根路径
单独加一条路由：e.GET("/swagger/index.html", func(c echo.Context) error { return c.File("./docs/index.html") })

注意：./docs 必须是 swag init -o 指定的输出目录，且该目录下必须存在 index.html、swagger.json 和 favicon-16x16.png 等文件。

Echo框架 5.1.0

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

下载

@Param 和 @Success 注释在 Echo 场景下的易错点

Echo 本身不参与注释解析，但 swag 对注释格式的要求在 Echo 项目里更容易踩坑——因为 Echo 的参数提取方式（c.Param("id")）和标准 http.Request 不同，但 swag 并不关心这个，它只认注释字段是否合规。

高频出错项：

@Param id path string true "用户ID" ✅ —— path 参数类型只能写 string，别写 int 或 uuid.UUID，否则报 cannot find type definition
@Param offset query int true "偏移量" ❌ —— query 参数不支持 int，必须写成 string，后端再自行转换
@Success 200 {object} model.User 要求 model.User 是导出结构体，且每个字段有 json: tag，否则 schema 里字段为空
数组响应必须写 {array} model.User，不是 {object} []model.User

中文注释乱码或文档标题仍是 “Swagger API”

这不是 Echo 或 swag 的 bug，而是两个硬性条件没满足：源文件编码必须是 UTF-8（无 BOM），且全局注释里必须显式设置 @title 和 @description。

在 cmd/main.go 顶部（package main 下方、import 上方）加：

// @title 用户服务 API 文档
// @version 1.0
// @description 这是基于 Echo 框架的微服务接口文档
// @termsOfService http://swagger.io/terms/
// @contact.name API Support
// @contact.url http://www.swagger.io/support
// @license.name Apache 2.0
// @license.url http://www.apache.org/licenses/LICENSE-2.0
// @host localhost:8080
// @BasePath /api/v1

如果仍乱码，检查 Go 源文件是否保存为 UTF-8 without BOM（VS Code 右下角可切换编码）；如果标题没变，确认 swag init 后重新生成了 docs/docs.go，且服务启动时没覆盖 docs.SwaggerInfo.Title。