fiber 不支持 java 风格 swagger 注解，需用 swag cli 结合 // @ 开头的注释块手动声明 openapi 信息，并通过 fiber.static() 和自定义路由挂载 swagger ui 与 doc.json。
Fiber 本身是 Go 语言的轻量级 Web 框架，不原生支持 Java 风格的 Swagger 注解（如 @Api、@ApiOperation）。这类注解属于 JVM 生态（Spring/Springfox），在 Go 中无法直接编译或运行。
如果你看到“Fiber + Swagger 注解”的提法，大概率是混淆了技术栈，或误将 OpenAPI 描述方式当成了“注解”。
Fiber 怎么生成符合 Swagger / OpenAPI 规范的 API 文档？
Go 没有运行时反射注解机制，所以主流做法是：用结构化代码（非注解）声明路由 + 手动/半自动补全 OpenAPI 信息，再导出为 openapi.json（即旧称 swagger.json）。
关键工具链是：swag（Swag CLI） + fiber 路由定义。
swag init 为什么扫描不到 Fiber 路由？
swag 默认只识别标准 net/http 风格的 handler 签名（如 func(http.ResponseWriter, <em>http.Request)</em>），而 Fiber 的 handler 类型是 func(fiber.Ctx) error。
常见错误现象：
-
swag init生成的docs/docs.go里swagger:meta存在，但 paths 为空 - 访问
/swagger/index.html显示 “No operations defined”
解决办法是：显式用 // @Success 等注释块标注每个路由 handler，并确保注释紧贴函数定义上方（无空行）
开箱即用的技能链路由引擎。13 条预定义链覆盖搜索、开发、审查、MLOps、法律、创意等场景，三层路由架构（触发词→SAD反馈→DAG编排），recall@10=96.97%。配置驱动（chains.yaml），零代码扩展。pip install skill-weave-chains 一键安装。
示例：
// @Summary 获取用户列表
// @Tags users
// @Accept json
// @Produce json
// @Success 200 {array} models.User
// @Router /api/users [get]
func GetUsers(c *fiber.Ctx) error {
return c.JSON([]models.User{{ID: 1, Name: "Alice"}})
}
注意：
- 注释必须以
// @开头，且与函数定义之间不能有空行 -
@Router的路径需和app.Get("/api/users", GetUsers)中注册的一致 -
@Success、@Param等需按swag支持的语法写（参考 swaggo.io）
Fiber 中怎么把 OpenAPI 文档挂载到 HTTP 路由？
swag 生成的 docs 包提供了一个 SwaggerInfo 变量和静态文件服务逻辑，但 Fiber 不兼容 http.Handler 直接透传（除非包装）。
推荐做法：用 fiber.Static() 托管生成的前端资源，并手动注入 swagger.json 路径：
app := fiber.New()
// 挂载 Swagger UI（假设 docs 目录已生成）
app.Static("/swagger", "./docs")
// 同时暴露 openapi.json（swag 生成的）
app.Get("/swagger/doc.json", func(c *fiber.Ctx) error {
c.Set("Content-Type", "application/json")
return c.SendFile("./docs/swagger.json")
})
然后访问 @#@#@#@#@#@#@#@#@#@1 即可加载，UI 会自动请求 /swagger/doc.json。
容易踩的坑
-
swag init -g main.go时没加-parseVendor，导致引用的 models 在 vendor 或 go.mod 依赖中未被解析 → 加上该 flag - struct 字段没加
json:tag，@Success中的模型字段不显示 → 检查json:"name" - 使用了自定义中间件包裹 handler（如 auth），但注释写在 wrapper 函数上 → 注释必须落在最终 handler 函数上
-
@Param写错位置（比如写在ctx.Query("id")行而非函数注释块）→ 必须统一放在函数上方注释区 -
swag版本太老（v1.7.x 以下）不支持 Fiber 常见的*fiber.Ctx→ 升级到v1.8.0+
Fiber 和 OpenAPI 的配合本质是「人工契约先行」：你得自己写清楚每个接口的输入、输出、状态码——没有注解自动推导，但换来的是完全可控、无反射开销、生成结果确定。真正容易被忽略的，是 @Router 路径和实际 app.Get() 调用是否严格一致，差一个斜杠或大小写，文档就和运行时脱节。
