Beego Swagger需同时满足三条件:router.go顶部规范注释、NSInclude注册路由、bee run -gendoc=true启动;否则404或空白;生产环境必须关闭EnableDocs。

Beego 自带 Swagger 集成能力,但不是“装完就能用”——必须同时满足三个条件:注释格式正确、bee run 启动时开启文档生成、路由定义符合命名空间规范。缺一不可,否则访问 /swagger/ 会 404 或页面空白。
beego 中的 Swagger 注释必须写在 routers/router.go 顶部
Beego 的文档解析器只认 routers/router.go 文件开头的全局注释块,其他地方写的 // @Title 全部忽略。常见错误是把注释写在 controller 方法上,那对 beego 文档生成完全无效。
-
routers/router.go文件开头必须有package routers,且紧随其后是完整注释块 - 必需字段包括:
// @APIVersion、// @Title、// @Description,缺一个bee run -gendoc=true就不生成文档 - 注释块不能被空行或代码打断,必须连续
- 示例位置:
// @APIVersion 1.0.0 // @Title Beego API // @Description My API Description // @Contact admin@example.com // @TermsOfServiceUrl http://example.com/terms // @License Apache 2.0 // @LicenseUrl http://www.apache.org/licenses/LICENSE-2.0.html package routers
路由定义必须用 beego.NSInclude 才能被扫描
Beego 文档工具只解析通过 beego.NSInclude 注册的 controller 方法,直接在 init() 里调用 beego.Router 或用 beego.Include 的路由不会出现在文档中。
- 必须使用命名空间(
beego.NewNamespace)+ 子命名空间(beego.NSNamespace)+ 包含控制器(beego.NSInclude)三层结构 - controller 方法上方可以加
// @Title、// @Param等,但仅用于补充说明,不参与路由发现 - 如果用了
URLMapping(),对应方法名必须和Mapping第一个参数一致,否则文档里显示为空操作 - 错误写法:
beego.Router("/user", &controllers.UserController{}, "*:Get")→ 不会被收录
bee run -gendoc=true -downdoc=true 启动才生效
Beego 的 Swagger 文档是运行时动态注入的,不是构建时静态生成。不加参数启动,/swagger/ 路由根本不会注册。
-
-gendoc=true:启用文档解析,扫描routers/router.go和已NSInclude的 controller -
-downdoc=true:自动下载 Swagger UI 到项目根目录下的swagger/文件夹(含dist/) - 首次运行后,
swagger/目录会存在;后续可删掉-downdoc=true,只用-gendoc=true - 访问地址固定为:
http://localhost:8080/swagger/(注意结尾斜杠),不是/docs或/swagger/index.html - 如果页面打开但提示 “Failed to load spec”,检查浏览器控制台是否 404
/swagger/swagger.json—— 这说明-gendoc=true没生效或注释有硬错误
生产环境务必关闭文档开关
EnableDocs = true 是开发期开关,一旦上线,Swagger 页面会暴露所有接口路径、参数、返回结构甚至注释里的调试提示。更危险的是,swagger.json 里默认包含 "host": "localhost:8080",前端调用会全部发向本地,而不是你的网关域名。
- 线上配置文件(如
conf/app.conf)中必须设:EnableDocs = false - 不要依赖 “只限制内网访问” 来保安全 —— 内网扫描工具一跑全出来
- 如果必须保留文档,应改用
swaggo/swag工具链 + 静态托管,和 beego 解耦,避免运行时注入风险 - 别信“加个 Basic Auth 就安全了” —— Swagger UI 本身不校验 auth,只是前端展示层
golang免费学习笔记(深入):立即使用
在学习笔记中,你将探索golang的核心概念和高级技巧!











