Fiber框架自动化API文档Swagger生成教程-Golang-PHP中文网

fiber框架需借助swag工具解析注释生成openapi文档，再用fiber-swagger/v2挂载ui；因其路由与中间件不兼容gin/echo方案，且官方fiber-swagger仅静态托管docs/swagger.json，不参与生成逻辑。

fiber框架自动化api文档swagger生成教程

Fiber 框架本身不带 Swagger 文档生成能力，但可借助 swag 工具静态解析 Go 源码注释生成 OpenAPI 3.0 文档，再用 swagger-files + fiber-swagger 挂载 UI —— 这是当前最轻量、最稳定、且与 Fiber 完全兼容的方案。

为什么不能直接用 gin-swagger 或 echo-swagger？

Fiber 的路由对象（fiber.App）和中间件签名与 Gin/Echo 不兼容，强行导入 gin-swagger/v2 会编译失败或 panic。官方维护的 fiber-swagger 是唯一适配 Fiber v2+ 的封装，它只负责挂载已生成的 docs/swagger.json，不参与文档生成逻辑。

fiber-swagger 依赖 github.com/swaggo/files/v2，不是旧版 swaggo/files
它不解析代码，也不读取注释，只做静态文件服务 —— 所以你必须先用 swag init 生成 docs/ 目录
若项目用了 go:embed 或多模块结构，swag init 默认不递归扫描子模块，需显式指定根路径

swag init 报 “failed to parse Go files” 怎么办？

这个错误不是 Fiber 的问题，而是 swag 的 AST 解析器卡在某个 Go 文件上。常见原因和对应操作：

Fiber框架 3.0.0

Fiber框架 3.0.0 版本源码包下载，适合从 Fiber v2 迁移到 v3、体验新绑定系统、HTTP 客户端、状态管理和迁移工具的开发者。

下载

项目里存在未修复的语法错误（比如少了个 }、go vet 过不去），先运行 go build ./ 确保能编译成功
用了实验性包（如 golang.org/x/exp）或 swag 尚未支持的泛型写法（如 func Do[T any]()），临时注释掉相关文件再试
注释里混入了非 UTF-8 字符（尤其 Windows 记事本保存的文件），用 VS Code 或 Vim 重新保存为 UTF-8
报错提示某行附近有 // swagger: 开头但格式错乱（比如冒号后没空格、漏换行），删掉或修正那行注释

如何让 Fiber 路由正确出现在 Swagger UI 中？

关键点：Fiber 不自动映射路由到文档，所有接口必须手动加 // @Summary 等注释，且路径字符串要和 app.Get("/api/v1/xxx") 完全一致（包括是否带 trailing slash）。

全局信息写在 main.go 顶部，例如：
// @title AI二维码工坊 API
// @version 1.0
// @basePath /api/v1
每个 handler 函数上方加接口级注释，路径必须匹配：
// @Router /encode [post] 对应 app.Post("/encode", encodeHandler)
如果用了 @basePath /api/v1，则 @Router 里写相对路径 /encode，不要写成 /api/v1/encode
挂载 UI 的路径必须是 /swagger/*any，不能是 /docs 或 /swagger/，否则前端请求 404

fiber-swagger 挂载后 UI 打开但接口列表为空？

这不是前端问题，大概率是 docs/docs.go 没被正确 import 或未生成。检查三件事：

确认已执行 swag init -g main.go -d ./（-d 指向包含 main.go 的目录），且输出中显示 create docs.go
确认 main.go 里 import 了生成的 ./docs 包（哪怕没显式使用），否则 Go 编译器会丢弃该包
确认 fiber-swagger 导入的是 v2 版本：
import "github.com/swaggo/fiber-swagger/v2"，老版本 fiber-swagger 已停止维护
启动后访问 /swagger/doc.json，看能否返回 JSON；如果 404，说明 docs/ 没挂载成功；如果返回空或报错，说明 docs/docs.go 未被编译进二进制