Beego Swagger文档生成需同时满足三个条件：注释格式正确（紧贴Controller方法、全英文半角、// @开头）、路由必须用beego.NewNamespace+NSInclude注册、启动时加bee run -gendoc=true参数，缺一不可。
Beego 的 Swagger 文档不是“写完注释就自动出来”，它必须同时满足三个硬性条件：注释格式正确、路由注册方式合规、启动时带 -gendoc=true 参数。缺一不可，否则 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）
接口自动化测试需配合 Postman 或直接调用 swagger.json
生成的 swagger.json 是标准契约，可直接导入 Postman 或 Swagger UI 进行调试：
- Postman 支持直接
Import → Link粘贴http://localhost:8080/swagger/swagger.json（需服务已启动且无跨域拦截） - 若遇跨域问题，可在
main.go中添加简单过滤器（仅开发环境）：if beego.BConfig.RunMode == beego.DEV { beego.InsertFilter("/*", beego.BeforeRouter, func(ctx *context.Context) { ctx.Output.Header("Access-Control-Allow-Origin", "*") ctx.Output.Header("Access-Control-Allow-Headers", "Content-Type,Token") ctx.Output.Header("Access-Control-Allow-Methods", "POST,GET,PUT,DELETE") }) } - 注意：Swagger UI 加载时默认请求
/swagger/swagger.json，所以静态路径必须设为beego.SetStaticPath("/swagger", "swagger")，且swagger/目录下必须包含该文件
最容易被忽略的是注释和路由的耦合关系——哪怕注释全对、-gendoc=true 也加了，只要路由没走 NewNamespace + NSInclude，整个 swagger.json 就是空的。这不是配置问题，是 beego 文档扫描器的硬编码逻辑。
