Beego v2.x及1.12+通过bee run -gendoc=true -downdoc=true可自动生成并启用Swagger文档，但需在conf/app.conf中显式设置EnableDocs = true（字符串格式），且Controller方法上方须严格按格式书写// @xxx注释块，包括必需的@router和匹配的@Param类型。

bee run -gendoc=true -downdoc=true 是当前 Beego（v2.x 及 1.12+）生成并启用 Swagger 文档的最简有效方式，无需手写 docs.go，也不用额外部署 Swagger UI。

---

EnableDocs = true 必须在 conf/app.conf 中显式开启

Beego 不会默认加载文档路由，即使你加了注解、跑了 bee run -gendoc=true，没开这个开关，/swagger/ 路径直接 404。

• 配置位置：确保修改的是运行时实际加载的 conf/app.conf（不是模板或测试配置）
• 值必须为字符串 true，不是布尔值或数字：

  EnableDocs = true

• 若使用多环境配置（如 app.prod.conf），需在对应环境文件中也设该值
• Beego 1.7.0+ 已废弃 _ "your_project/docs" 导入，强行添加反而可能触发重复注册 panic

---

注解必须写在 controller 方法上方，且格式严格

Swagger JSON 的字段（如 @Param、@Success）由 Beego 的 CommentRouter 解析器提取，它只认特定格式的注释块，不识别任意注释或空行分隔。

Beego框架 2.3.5

Beego框架 2.3.5 版本源码包下载，适合关注表单空值、函数注释名和 nil 返回值修复的 Go Web 开发者。

下载

• 每个 handler 方法上方必须有连续的 // @xxx 块，不能穿插普通注释
• @router 必须存在，且路径和方法要匹配实际注册的路由（例如 @router /users [get] 对应 Get("/users", ...)）
• @Param 类型必须与实际接收方式一致：body 表示 JSON body 解析，query 表示 URL 查询参数，path 表示路径变量（如 /user/:id）
• 示例正确写法：

  // @Title Get user list
  // @Description get all users
  // @Param page query int false "page number"
  // @Param limit query int false "page size"
  // @Success 200 {object} []models.User
  // @router /users [get]

漏掉 @router 或类型写成 body 但实际是 query，会导致字段不显示或文档解析失败。

---

swagger.json 生成时机与常见失效场景

bee run -gendoc=true 会在每次启动前扫描 controller 注释并重写 swagger.json，但它不监控文件变更 —— 修改注释后必须重启进程才生效。

• 如果 swagger.json 内容陈旧，先确认是否真的重启了服务（不是 Ctrl+C 后直接回车，而是完整退出再 bee run -gendoc=true -downdoc=true）
• -downdoc=true 仅下载 Swagger UI 到 swagger/ 目录，不会校验或覆盖已有 index.html；若你手动改过 index.html 里的 url，请确认它指向的是 /swagger/swagger.json（不是 localhost:8080/swagger.json 这类绝对路径）
• 使用 bee pack 打包时，swagger/ 目录会被自动包含，但若项目启用了 Go Modules 且未在 go.mod 中声明依赖，bee 可能无法定位 controller 包，导致 swagger.json 为空 —— 此时应检查 go list ./... | grep controller 是否能列出你的控制器路径

---

Beego 的 Swagger 集成本质是「静态注释扫描 + 内置 HTTP 路由暴露」，它不代理请求、不运行时反射结构体，所有字段都靠你写的注释驱动。最容易被忽略的，是注释格式的机械性 —— 少一个空格、错一个单词、多一行空行，swagger.json 里就少一条参数。