fiber集成swagger需手动构造openapi 3.0 json/yaml并挂载路由，因swag init不兼容fiber.ctx签名，无法自动识别注解；必须修正swaggerinfo.host、basepath等字段或直接静态托管openapi.json与swagger-ui-dist。
Fiber 是一个用 Go 编写的高性能 Web 框架，本身不内置 OpenAPI/Swagger 支持，需要借助第三方库生成文档。它不像 Spring Boot 那样有成熟的 springfox 或 springdoc 生态，所以集成 Swagger 的关键不是“开启注解开关”，而是**手动构造 OpenAPI 3.0 规范 JSON/YAML，并挂载到路由上供 swagger-ui 加载**。
下面分几个实际开发中会遇到的具体问题来说明怎么做：
为什么直接用 swag init 在 Fiber 项目里跑不通
因为 swag init（来自 swaggo/swag）默认扫描的是 net/http 风格的 handler（如 func(http.ResponseWriter, *http.Request)），而 Fiber 的 handler 签名是 func(*fiber.Ctx) error，类型不兼容。它无法识别 @Summary、@Param 等注解是否真的被某个 f.Get(...) 调用关联上了。
常见错误现象：swag init 成功生成 docs/docs.go，但访问 /docs/index.html 时显示 “No API definition provided” 或空白 Swagger UI。
- 根本原因：生成的
docs/docs.go里SwaggerInfo的Host、BasePath没配对当前 Fiber 服务地址 -
swag不知道你把 API 挂在了/api/v1还是根路径，也没法自动推导consumes/produces - 如果你用了
f.Group()或中间件（如 JWT），swag更无法感知请求上下文
推荐做法：用 swaggo/files + 手动注册 OpenAPI JSON 路由
跳过 swag init 自动生成文档结构的环节，改用更可控的方式——自己写一个符合 OpenAPI 3.0 格式的 JSON（或用工具生成后固化），再通过 Fiber 的静态路由暴露出去。
实操建议：
- 用在线工具（如 Swagger Editor）先写好 YAML，导出为
openapi.json - 把
openapi.json放进项目docs/目录下 - 在 Fiber 启动时加一条路由：
f.Static("/docs", "./docs")，然后访问/docs/openapi.json确认能返回内容 - 再引入
swaggo/files提供的 UI：f.Get("/swagger", func(c *fiber.Ctx) error { return c.SendFile("./node_modules/swagger-ui-dist/index.html") })（需提前npm install swagger-ui-dist） - 最后确保 UI 页面里
url指向的是你刚暴露的/docs/openapi.json
如果坚持用注解自动生成，必须补全三处硬编码
有人尝试用 swag init -g main.go -o ./docs 强行生成，结果 UI 加载失败。这不是工具问题，是你没告诉它“文档该长什么样”。必须手动修正生成后的 docs/docs.go 中以下字段：
-
SwaggerInfo.Title：不能留空，否则 UI 不显示标题 -
SwaggerInfo.Version：建议设为os.Getenv("VERSION")或硬编码"1.0.0" -
SwaggerInfo.Host：填你实际部署的域名+端口，比如"api.example.com:8080"；本地调试可设为"localhost:3000" - 最关键的是
SwaggerInfo.BasePath：要和你在 Fiber 中注册 API 路由的前缀一致，比如你写的是f.Group("/api/v1")，这里就必须设为"/api/v1"
否则 Swagger UI 发起的预检请求会 404，连带所有 Try it out 按钮失效。
别忽略 CORS 和生产环境路径映射
Swagger UI 是前端页面，它用 fetch 调用你的 API，所以跨域问题比普通浏览器请求更敏感。Fiber 默认不带 CORS 中间件。
容易踩的坑：
- 没启用
f.Use(cors.New())，UI 上点击 Execute 报Failed to fetch - API 实际部署在 Nginx 后面，路径被重写了（比如
/api/v1/xxx→proxy_pass http://backend/），但 OpenAPI 文档里写的还是/api/v1/xxx，导致 UI 请求发到了错误路径 - Swagger UI 页面加载时默认读取当前 URL 的 origin，如果你用
file://打开本地 HTML，fetch 会被浏览器直接拦截
解决办法：统一用 http://localhost:3000/swagger 这类服务化方式访问 UI，且确保后端响应头含 Access-Control-Allow-Origin: *（开发期）或精确域名（生产期）。
openapi.json，再用最朴素的 Static 和 SendFile 拉起来——这样没有版本兼容问题，没有注解解析失败，也没有运行时 panic。
