Fiber 项目配 Swagger 必须用 swaggo/fiber-swagger 而非 gin-swagger；swag init 需正确指定 -d（含 handler 函数的目录）和 -g（含 @title 和 fiber.New() 的文件），handler 函数需紧贴 // @Summary 注释，挂载用 app.Get("/swagger/*", fiberSwagger.WrapHandler(...))，struct 字段须导出且含有效 json tag。
Fiber 项目配 Swagger 文档，不能直接套用 Gin 的那一套——gin-swagger 对 Fiber 完全无效，必须换用 swaggo/fiber-swagger，且注释解析逻辑、挂载方式、路径处理都不同。
swag init 扫不到 Fiber handler？检查 -d 和 -g 是否覆盖真实路由注册点
swag 是静态扫描器，不运行代码，只读源文件。Fiber 的路由通常分散在 internal/handler、api/v1 或 pkg/route 下，而 main.go（或 cmd/app/main.go）里只调用 app.Get(...)，这些调用本身不会被解析——它只认带 // @Router 注释的函数定义。
- 所有含
// @Summary的 handler 函数必须在-d指定的目录下，例如：swag init -d internal/handler -d api/v1 -
-g必须指向含全局 API 元信息（如// @title）和主fiber.New()初始化的文件，通常是cmd/app/main.go；若写成main.go但实际路径是cmd/server/main.go，会因 import 路径不匹配导致扫描失败 - handler 文件的
package不能是main（除非它真包含路由注册），推荐统一用package handler或package v1，否则 swag 可能跳过整个文件 - 确保每个 handler 函数上方紧贴着注释块，
// @Summary必须是第一行，前面不能有空行或/* */块注释
Fiber 挂载 Swagger UI 报 404？别用 Static，必须用 fiber-swagger.WrapHandler
Fiber 的静态文件服务（app.Static）无法正确处理 Swagger UI 的 History API 回退逻辑，直接挂载 docs/ 目录会导致 /swagger/swagger-ui.css 等资源 404，页面空白。
- 安装专用适配器：
go get github.com/swaggo/fiber-swagger（不是gin-swagger） - 挂载路由必须用通配符：
app.Get("/swagger/*", fiberSwagger.WrapHandler(swaggerFiles.Handler))，注意是/*，不是/*any（那是 Gin 的写法） -
docs/docs.go必须存在且已生成，否则swaggerFiles.Handler是 nil；执行swag init后手动确认该文件是否含init()函数和有效 imports - 挂载顺序无硬性要求，但建议放在所有业务路由之后、
app.Listen()之前
@Param 和 @Success 写错类型？Fiber 不影响，但 swag 解析器仍受限
Fiber 框架本身对注释无感知，问题全出在 swag CLI 的类型推导能力上。它不理解 Go 的 type alias、泛型、或未显式声明的嵌套结构。
使用 uber-go/dig 在 Golang 中实现依赖注入——基于反射容器，提供 Provide/Invoke、dig.In/dig.Out 参数与结果对象，支持命名依赖等
立即学习“go语言免费学习笔记（深入）”；
- 路径/查询参数只认基础类型：
string、int、int64、bool、float64；写uuid.UUID或models.ID会报cannot find type definition - 请求体（
in: body）必须指向一个已定义的 struct，且该 struct 上方需有// @Model注释，字段必须首字母大写 + 含json:tag，否则字段不显示 - 数组参数不能简写：
@Param ids query []string true "ID列表"❌；正确写法是：@Param ids query array true "ID列表" collectionFormat:multi items.type:string - 响应类型写
{object} UserResponse时，UserResponse必须在当前 module 可见（即 import 路径正确），且不能是未导出 struct 或嵌套在函数内
中文乱码或字段全空？根源不在 Fiber，而在文件编码与 struct 导出规则
Swagger UI 加载后中文变 \u4f60\u597d，或点击响应 schema 显示空对象，和 Fiber 无关，是 swag 解析阶段就失败了。
- 用
file -i handler.go检查文件编码，必须是UTF-8；VS Code 或 GoLand 若保存为 UTF-8 with BOM，swag 会静默跳过该文件 - 所有要出现在文档里的 struct 字段，必须首字母大写（导出），且
json:tag 不能是-或空字符串，例如：Name string `json:"name"`✅，name string `json:"name"`❌ - 如果用了
encoding/json以外的序列化库（如easyjson），swag 无法识别其 tag，字段会消失 - 注释中写了
@Success 200 {object} User，但User结构体没加// @Model，swag 就不会生成其 schema，UI 里只显示object
最易被忽略的是：Fiber 项目常把路由注册和 handler 分离，swag init 却只看注释位置，不看调用链。哪怕 app.Get("/user", handler.GetUser) 写得再规范，只要 GetUser 函数上方没注释块，它就不会进 swagger.json —— 这和框架无关，是工具链的硬约束。
