Beego自动生成Swagger文档需同时满足三个硬性条件:注释紧贴Controller方法且格式正确、路由必须用beego.NewNamespace+NSInclude注册、启动时加bee run -gendoc=true参数,缺一不可。

Beego 自动生成 Swagger 文档不是配个开关就行,必须同时满足三个硬性条件:注释格式正确、路由用 NewNamespace+NSInclude 注册、启动加 -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 - 所有注释行必须以
// @开头,不能是/* @ */或其他形式
路由必须用 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://www.php.cn/link/543a84894716c6c0ed6cabe60aac9945) - 首次运行后,确保
swagger/index.html存在;访问http://localhost:8080/swagger/才能加载 UI - 如果页面空白或报 404,先确认文件是否存在,再看浏览器控制台是否提示跨域或 JSON 解析失败(常见于
index.html请求的是/swagger/swa而非/swagger/swagger.json)
最容易被当成配置失效的问题,其实是缓存和路径错位——比如 swagger/ 目录被误删、index.html 里硬编码了错误的 JSON 路径、或者本地用 file:// 协议直接打开 HTML 导致跨域。这些地方不报错,但文档就是不显示,得一个个手动核对。


















