swag init 扫不到 Fiber handler 函数，因默认仅扫描同 module 的当前目录文件且不解析路由注册逻辑；需显式指定 -d 目录和 -g 入口文件，并确保 handler 非 main 包、有正确注释与 blank import。
swag init 扫不到 Fiber handler 函数？路径和入口必须显式指定
swag 默认只扫描当前目录及子目录下属于同一 module 的 .go 文件，且不会自动识别 fiber.App 的路由注册逻辑——它只认注释块是否在函数上、函数是否被入口文件“触达”。Fiber 项目常把路由分散在 internal/router 或 pkg/api，而 main.go 只负责 app.Listen()，这种结构下 swag init 极易漏掉所有接口。
- 必须在模块根目录（含
go.mod）执行命令，否则 import 路径解析失败 - 用
-d显式指定 handler 所在目录：swag init -d internal/router -d pkg/api - 用
-g指定真正调用app.Get()/app.Post()的入口文件，例如：swag init -g cmd/app/main.go；若没加，docs/docs.go中的SwaggerInfo不会包含任何路由 - handler 函数所在文件不能是
package main（除非它真注册了路由），推荐统一用package router，并确保该包有合法import声明和无语法错误
Fiber 路由挂载后 /swagger/index.html 404？别用 Static，要用 *any 通配符
Fiber 的静态资源路由不支持 SPA 的 History API 回退机制，直接 app.Static("/swagger", "./docs") 会导致 /swagger/swagger-ui.css 等子资源全部 404，页面空白。正确方式是让所有 /swagger/xxx 请求都落到 Swagger UI 的单页入口。
- 确认
swag init成功后存在docs/docs.go和docs/swagger.json；不存在说明上一步已失败 - 挂载路由必须用：
app.Get("/swagger/*any", swagger.Handler)（注意*any不能省，这是 Fiber 官方推荐写法） - 必须 blank import docs 包：
import _ "your-module-name/docs"，否则swagger.Handler拿不到初始化后的SwaggerInfo - 不要手动复制
docs/到部署目录——Fiber 通过swagger.Handler内置提供资源，二进制打包时无需额外处理静态文件
@Param 和 @Success 注释不生效？Fiber 不自动推导参数，全靠字面匹配
swag 不读取 Fiber 的 c.Params、c.Queries 或 c.Body，也不反射 Go 类型。它只按注释字符串逐字解析：字段名错一个、类型写错大小写、结构体未导出、json tag 缺失，都会导致参数栏空白或响应显示 object。
- 路径参数写法：
// @Param id path string true "用户ID"，类型只能是string、int、bool、float64；别写int64或自定义类型 - 请求体必须指向已定义结构体：
// @Param req body model.UserCreate true "用户数据"，且该结构体上方需有// @Model注释（可选但建议） - 响应结构体字段必须首字母大写 +
json:"xxx"tag，否则 schema 里字段为空；匿名 struct 或map[string]interface{}不支持生成 schema - 数组参数不能写
type: []string，得用：// @Param ids query array true "ID列表" collectionFormat:multi items.type:string
中文乱码、example 不显示、生产环境暴露风险？编码与开关要硬控制
UTF-8 BOM、未导出字段、example 标签位置不对，都会让 Swagger 页面显示 \u4f60\u597d 或样例缺失。更关键的是，swagger.Handler 默认无访问控制，上线后等于把全部接口细节白给攻击者。
- 所有
.go文件保存为 UTF-8 无 BOM 编码；编辑器如 VS Code 需关掉“Auto Guess Encoding” -
example必须写在 struct 字段 tag 里：Email string `json:"email" example:"test@example.com"`，写在注释里无效 - 开发环境启用：
app.Get("/swagger/*any", swagger.Handler)；生产环境必须移除该路由，或加中间件拦截：if os.Getenv("ENV") != "dev" { app.Get("/swagger/*any", func(c *fiber.Ctx) error { return c.Status(404).SendString("Not Found") }) } - 别信 “只改路由前缀就安全”——只要
docs/docs.go被导入，swagger.Handler就能响应，必须从构建流程或运行时开关双重控制
Fiber 集成 Swagger 最容易卡在「注释写了但没效果」，根本原因不是工具不行，而是 swag 的解析逻辑极其机械：它不猜、不推、不报错，只匹配。你漏掉一个 @Summary，整个函数就静默消失；你结构体字段小写，schema 就空着；你没 blank import docs，页面就 404。这些点不靠试错，得靠规则对齐。
