直接用 swag cli 工具即可，fiber 无内置 swagger 支持但 go 原生特性使 swag 注释解析稳定；注释需以 // @ 开头、置于函数声明上方、无空行，且必须含 @summary 和 @description；生成 docs 后通过 swagger.handler 或 fiber.static 挂载路由暴露 ui，注意 import _ "./docs" 和 ci 中执行 swag init。
直接用 swag CLI 工具就行，Fiber 本身不内置 Swagger 支持，但它的 Go 原生特性让 swag 注释解析非常稳定——只要注释写对、生成命令跑通，docs 目录就能出来，再配个路由挂载就完事。
为什么不用 springdoc 或 springfox？
Fiber 是 Go 语言框架，和 Java 的 Spring 生态完全无关。Springfox、springdoc-openapi 这些是 JVM 侧的 OpenAPI 实现，不能用于 Go 项目。强行套用会连编译都过不了。
Go 生态里事实标准就是 swaggo/swag，它专为 Go 设计，直接解析 AST，不依赖运行时反射，也不要求你改路由注册方式——这对 Fiber 这种轻量、手动注册路由的框架特别友好。
怎么写注释才能被 swag 正确识别？
swag 只认特定格式的注释块，必须以 // @ 开头，且必须放在函数声明上方（不是函数体内），且不能有空行隔开。
-
// @Summary和// @Description必须都有，否则该接口不会出现在文档中 -
// @Tags推荐加上，不然所有接口都归到 “default” 分组，后期难管理 -
// @Param中的in字段要和 Fiber 实际取参方式一致：query →c.QueryParam，path →c.Params，header →c.Get -
// @Success和// @Failure的响应结构要写真实类型，比如{object} models.User，不是map[string]interface{}
示例：
// GetUser godoc
// @Summary 获取用户信息
// @Description 根据ID查询用户详情
// @Tags user
// @Accept json
// @Produce json
// @Param id path string true "用户ID"
// @Success 200 {object} models.User
// @Failure 404 {object} models.ErrorResponse
// @Router /users/{id} [get]
func GetUser(c *fiber.Ctx) error {
id := c.Params("id")
// ...
}
生成 docs 目录后怎么在 Fiber 里暴露 Swagger UI？
swag 生成的是静态文件（docs/swagger.json 等），Fiber 没有内置中间件自动托管，得手动挂载两个路由：
- 一个路由返回
swagger.json内容（通常用docs.Handler()，但需先调用swag.Install()） - 另一个路由托管前端 HTML/JS/CSS（推荐用
fiber.Static()指向docs目录）
注意顺序：必须先 swag.Init() 或确保 docs/docs.go 已生成并导入，否则 docs.Handler() 会 panic。常见错误是忘记 import _ "./docs" 导致空指针。
典型挂载写法：
app.Get("/swagger/*", swagger.Handler(swagger.Config{
DeepLinking: true,
DocExpansion: "none",
}))
// 或更轻量的手动静态托管（如果不想用 swagger.Handler）
app.Static("/swagger", "./docs")
访问 http://localhost:3000/swagger/index.html 即可看到 UI。
容易忽略的构建时机和 CI 问题
swag init 是构建期动作，不是运行时动作。CI 流水线里如果没执行这步，docs/docs.go 就是旧的，上线后文档和代码对不上——这是最常被线上排查踩到的坑。
建议在 Makefile 或 CI 脚本里固化流程：
- 每次提交前跑
swag init -g main.go -o ./docs - Git hook 或 CI 检查
docs/docs.go是否比main.go更旧（可用git status --porcelain docs/docs.go判断是否已修改） - 禁止将
docs/docs.go设置为 gitignore——它必须进版本库，否则其他协作者无法启动 UI
另外，Fiber v2.50+ 默认禁用 MIME 类型自动推断，若静态托管 Swagger UI 时 JS/CSS 加载失败，记得显式设置：app.Static("/", "./docs", fiber.Static{Compress: true, ByteRange: true})。
