Fiber 无原生 Swagger 支持，需手动编写 OpenAPI 规范或借助 swag 解析注释生成 docs 并集成 fiber-swagger；关键点包括注释格式、docs 目录生成、路由挂载及生产环境禁用。
Fiber 是 Go 语言的轻量级 Web 框架，本身不内置 OpenAPI/Swagger 支持，也没有类似 Spring Boot 的自动扫描注解机制。它不识别 @Api、@ApiOperation 这类 Java 风格注解，所以不能像 SpringBoot 那样靠注解驱动生成文档。直接“集成 Swagger”在 Fiber 中本质是：**手写 OpenAPI 3.0 YAML/JSON 规范文件 + 嵌入 Swagger UI 页面**，或借助第三方工具辅助生成。
下面分几个实际能落地的路径说明：
为什么 Fiber 没有原生 Swagger 注解支持
Fiber 的设计哲学是极简和显式——路由、中间件、响应都由代码直接定义，不依赖反射或运行时元数据提取。Go 语言本身也不支持运行时注解（如 Java 的 @xxx），所有 “Swagger 注解” 都只是注释（// @Summary Get user），不会被编译器或框架读取。
这意味着：Fiber 项目里写的 // @Param 注释，除非用外部工具（比如 swag）解析并生成 docs/swagger.json，否则对框架完全透明，也不会自动生效。
- 常见错误现象：
swag init后访问/swagger/index.html页面空白，或报Failed to load spec—— 很可能是因为没生成docs/docs.go或没注册fiberSwagger中间件 - Go 模块路径必须匹配
swag init -g指定的入口文件所在包路径，否则解析失败（例如入口是main.go，但包名写成package main而不是模块根路径） -
swag只解析// @...开头的注释，且必须紧贴函数声明上方，空行或错位会导致字段丢失
用 swag + fiber-swagger 手动生成并嵌入 UI
这是目前最主流、最可控的方式。核心是三步：swag init 生成 docs/ 目录 → 引入 fiber-swagger → 挂载路由。
- 安装
swagCLI：go install github.com/swaggo/swag/cmd/swag@latest - 在
main.go顶部添加通用注释（必须）：// @title User API // @version 1.0 // @description This is a sample API server. // @host localhost:3000 // @BasePath /api/v1
- 为每个 handler 添加注释，例如：
// @Summary Get user by ID // @Tags users // @Accept json // @Produce json // @Param id path int true "User ID" // @Success 200 {object} models.User // @Router /users/{id} [get] func GetUser(c *fiber.Ctx) error { ... } - 执行
swag init -g main.go -o docs（确保main.go包名为模块根路径，如github.com/yourname/project） - 在路由注册处加入：
import "github.com/swaggo/fiber-swagger" app.Get("/swagger/*", fiberSwagger.WrapHandler)
用 openapi3-go 手写规范并动态挂载
适合接口稳定、团队习惯契约先行的场景。绕过 swag 解析，直接用 Go 构建 openapi3.T 对象，再通过 fiber 返回 JSON 或提供 UI 资源。
- 优势：完全可控，可复用已有 OpenAPI 文件，支持复杂 schema 引用、security scheme、x-extension
- 劣势：无自动化，每次接口变更需手动同步 YAML/Go 结构体
- 关键点：
openapi3.T实例需调用Validate()，否则fiberSwagger可能加载失败；静态资源路径要配对（如docs/swagger.json需通过app.Static或app.Get("/swagger.json", ...)暴露） - 不要直接返回
openapi3.T.MarshalYAML()，要用json.Marshal输出 JSON 格式（Swagger UI 只认 JSON）
生产环境必须关掉 Swagger UI
Fiber 没有 profile 概念，开关全靠代码控制。别只靠 if os.Getenv("ENV") == "dev"，容易漏掉静态资源路由。
- 推荐方式：用
app.Group隔离，只在开发环境注册：if os.Getenv("ENV") == "development" { swaggerGroup := app.Group("/swagger") swaggerGroup.Get("/*", fiberSwagger.WrapHandler) } - 更安全的做法：构建时用
-tags=swagger控制，把 Swagger 相关 import 和路由注册包在//go:build swagger下，上线编译时去掉该 tag - 线上若意外暴露
/swagger，攻击者可直接看到全部接口路径、参数、甚至示例请求体 —— 这比泄露接口多得多
Fiber 的 Swagger 文档链路是「人工契约主导」，没有魔法。最容易被忽略的是：注释格式是否严格符合 swag 解析规则、docs/ 是否被 Git 忽略导致 CI 环境缺失、以及 UI 路由是否真的只存在于非生产环境。这三个点出问题，90% 的“集成失败”就发生了。
