Beego自动化API文档需同时满足三条件：启用EnableDocs=true配置、控制器方法带标准Swagger注释（如@Title、@Param）、使用bee run -gendoc=true -downdoc=true启动，并且路由必须通过NewNamespace+NSInclude方式注册，缺一不可。
Beego 的自动化 API 文档不是“开箱即用”的功能，必须同时满足三个条件：启用文档开关、正确书写注释、使用 bee run 带参数启动——缺一不可，否则访问 /swagger 会 404 或返回空 JSON。
启用 EnableDocs 配置项
这是最基础但最容易被跳过的一步。Beego 不默认开启文档生成，必须在 conf/app.conf 中显式设置：
-
EnableDocs = true（注意大小写，enabledocs或enable_docs都无效） - 该配置需位于
[dev]或全局段（如无分段则直接写在文件顶部） - 如果项目运行在
prod模式，还需在[prod]段重复写一次，否则线上环境文档不可见
控制器方法必须带标准 Swagger 注释
Beego 只解析以 @Title、@Description、@Param 等前缀开头的注释块，且必须紧贴在 controller 方法定义上方（不能隔空行）：
-
// @Title GetUser和// @Description Get user by ID是必需字段，缺一则整个接口不进文档 -
@Param id path string true "user ID"中的path表示参数位置，若实际是 query 参数，得写成@Param id query string true "user ID" - 返回类型要写准确：
@Success 200 {object} models.User，其中models.User必须是已定义的 struct，拼错或未导入包会导致字段为空 - 不支持普通函数或非 controller method 的注释解析，比如
func helper()上的注释不会被采集
用 bee run -gendoc=true -downdoc=true 启动
仅靠 bee run 不会触发文档生成；必须加两个 flag：
-
-gendoc=true：强制每次编译时重新扫描注释并生成docs/doc.go -
-downdoc=true：自动从https://github.com/beego/swagger下载最新版 Swagger UI 到项目根目录的swagger/文件夹 - 首次执行后，
swagger/目录下应有index.html、swagger.json等文件；若目录为空，说明下载失败，可手动下载 release 包解压进去 - 浏览器访问
http://127.0.0.1:8080/swagger/，不是/docs或/swagger/index.html—— 路由由 Beego 内部注册，硬编码为/swagger
路由必须用 NewNamespace + NSInclude 方式注册
文档生成器只识别特定路由结构，传统 beego.Router() 或 beego.Include() 直接注册的 controller 不会被收录：
- 必须使用
beego.NewNamespace("/v1", ...)，一级路径为版本号 - 子模块必须用
beego.NSNamespace("/user", beego.NSInclude(&controllers.UserController{}))形式 - 嵌套层级不能超过两层（如
/v1/user/profile不支持），否则/swagger页面能打开，但对应接口消失 - router.go 里所有 namespace 必须最终通过
beego.AddNamespace(ns)注册，漏掉就整组路由不进文档
最容易被忽略的是注释与路由结构的耦合性：哪怕配置全对、命令参数全加，只要 controller 方法上少一个 @Title，或路由没走 NewNamespace，Swagger 页面就显示为空白或 404。建议先跑通一个最简 controller 示例，再逐步扩展。
