beego集成Swagger需同时满足注释格式正确、路由用NewNamespace+NSInclude注册、启动加-gendoc=true参数，缺一不可；否则swagger.json为空或字段缺失。
beego 集成 Swagger 生成接口文档不是“配个开关就出来”，它必须同时满足三个硬性条件：注释格式正确、路由注册方式合规、启动命令带参数。缺一不可，否则 swagger.json 为空或字段缺失。
注释必须写在 Controller 方法上方且严格符合 Swagger 格式
beego 只扫描 Controller 方法正上方的块注释，不解析结构体、数据库 schema 或普通注释行。常见失效原因包括：
- 注释没紧贴函数定义，中间夹了空行或 // xxx 普通注释
- 使用中文标点（如“：”“，”），应全用英文半角
- @Param 中参数名与 @router 路径占位符不一致：比如路径是 /staticblock/:key，但注释写成 @Param id path string true "xxx"
- @Success 或 @Failure 的返回类型没写完整包路径，例如写 {object} Customer 而非 {object} models.Customer
- 所有注释行必须以 // @ 开头，不能是 /* @ */ 或其他形式
路由必须用 beego.NewNamespace + NSInclude 注册
beego 文档生成器完全忽略 beego.Router、beego.AutoRouter 和手动 AddRouter。只认嵌套命名空间结构：
- 必须在 routers/router.go 的 init() 函数中调用 beego.AddNamespace(ns)
- ns 必须由 beego.NewNamespace 构建，且至少两级：一级为版本（如 /v1），二级为模块（如 /customer）
- 控制器必须显式传入 NSInclude(&controllers.XXXController{})；不能传变量名，也不能用匿名 struct
- 三级及以上嵌套不会被解析，写了也白写
启动时必须加 bee run -gendoc=true -downdoc=true
仅在 conf/app.conf 中设 EnableDocs = true 不起作用，也不会实时更新文档：
- -gendoc=true 触发每次编译时重扫注释并重写 swagger.json 和 swagger.yml
- -downdoc=true 检查项目根目录是否有 swagger/ 文件夹；没有就自动从 GitHub 下载解压（地址：https://github.com/beego/swagger/archive/v2.zip）
- 首次运行后，确保 swagger/index.html 存在；访问 http://localhost:8080/swagger/ 才能加载 UI
- 如果页面空白或报 404，先确认文件是否存在，再看浏览器控制台是否提示跨域或 JSON 解析失败（常见于 index.html 请求的是 /swagger/swa 而非 /swagger/swagger.json）
缓存和路径错位最容易被当成配置失败
90% 的“文档没更新”其实是假象： - 浏览器访问/swagger/ 时，index.html 默认请求的是 /swagger/swagger.json，但若你改过静态路由或用了反向代理，路径可能错位
- bee run 后没看到变化？先清掉浏览器缓存，再检查 swagger.json 文件内容是否真为空或字段缺失
- 不要依赖 bee generate docs，该命令已废弃；1.7+ 版本只认 -gendoc=true 编译时注入
路径和注释对不上、命名空间少了一级、启动漏了参数——这三个地方只要错一个，swagger.json 就是空的，别怀疑框架，先回去逐条核对。
