beego swagger文档生成需满足三个条件：项目由bee api创建、enabledocs=true启用、控制器方法有规范注解；否则会出现404、空白页或swagger.json为空等问题。
Beego 内置的 Swagger 文档生成能力是开箱即用的，但必须满足两个硬性条件：项目结构为 bee api 生成、且 EnableDocs = true 已在配置中启用。用 bee new 创建的项目即使手动加注解，bee run -gendoc=true 也大概率不生效——这不是配置问题，而是路由注册机制不同导致注解无法被扫描到。
为什么 bee run -gendoc=true 没反应？
常见现象是命令执行后控制台无报错，但访问 http://localhost:8080/swagger/ 显示 404 或空白页。根本原因有三个：
-
conf/app.conf中未设置EnableDocs = true（注意大小写，不能写成enabledocs或enable_docs） - 项目不是用
bee api project_name创建的，而是bee new或手建；后者缺少routers/commentsRouter_controllers.go这类由 bee 自动生成的注解绑定文件 - 控制器方法上缺少符合 Beego 规范的注解，比如漏掉
// @router /users [get]，或参数声明格式错误（如写成@Param id query int true "user id"却没加空格）
swagger.json 生成失败或内容为空？
执行 bee run -gendoc=true 后，swagger/swagger.json 文件存在但只有 {} 或字段极少，说明注解未被正确识别。关键检查点：
- 注解必须写在 controller 方法上方，且紧贴函数定义（中间不能有空行）
- 只支持
NSInclude引入的 controller；如果你在routers/router.go里直接用beego.Router或beego.NSRouter手动注册，这些路由不会进 swagger -
// @Param的第三个字段必须是类型关键字：string、int、bool、json等，不能写models.User或自定义 struct 名 - Beego 1.12+ 默认只扫描
controllers/下的 go 文件，若把 handler 放在子目录（如controllers/v1/）则不会被处理
如何让 Swagger UI 正确加载本地 swagger.json？
直接双击打开 swagger/index.html 会因跨域报错，这是浏览器限制，不是 Beego 问题。正确做法是依赖 Beego 自带的静态服务：
- 确保
swagger/目录在项目根目录下（不是子模块或外部路径） - 启动时用
bee run -downdoc=true -gendoc=true，Beego 会自动下载并解压 swagger-ui 到该目录 - 不要手动修改
index.html里的url字段——Beego 已在运行时注入正确的http://localhost:8080/swagger/swagger.json - 如果仍加载失败，检查浏览器控制台 Network 标签页，看是否返回 404；常见原因是
swagger.json文件权限被拒，或 Go 进程未监听 8080 端口（比如 app.conf 里写了HttpPort = 9000）
最易被忽略的一点：Beego 的 swagger 注解解析器对缩进和换行极其敏感。哪怕多一个空格、少一个斜杠，整个注解块就会被跳过，且不报任何警告。建议每次改完注解后，先运行 bee generate docs 看是否能输出非空 JSON，再启动服务验证 UI 渲染效果。
大量免费API接口：立即使用
涵盖生活服务API、金融科技API、企业工商API、等相关的API接口服务。免费API接口可安全、合规地连接上下游，为数据API应用能力赋能！
