Buffalo框架不内置OpenAPI文档生成功能，需用swaggo在handler上写注释并执行swag init生成swagger.json，再通过ServeFiles挂载到带版本前缀的路由（如/api/v1/docs）下。
Buffalo 框架本身不生成 OpenAPI/Swagger 文档，没有内置 buffalo docs 或类似命令；所有文档必须手动维护或借助第三方工具桥接生成，否则上线后 API 接口将无标准描述、难被前端或测试团队消费。
为什么 buffalo routes 不等于 API 文档
buffalo routes 只输出 METHOD PATH HANDLER 三元组，不包含请求体结构、响应字段、状态码说明、参数类型或示例——它只是路由注册快照，不是契约文档。比如它显示 POST /api/users → UsersCreate，但不会告诉你 body 需要 {"name": "string", "email": "string"}，也不会标注 400/422 错误的返回格式。
- 运行
buffalo routes后得到的纯文本无法被 Swagger UI 渲染 - 它不感知
c.Bind()解析的 struct 字段标签（如json:"name" validate:"required"） - 中间件注入的 header（如
X-Request-ID）、认证方式（Bearer）完全缺失
用 swaggo + Buffalo 手动补全注释生成
最可行的路径是放弃框架集成幻想，改用 swaggo/swag 工具链，在 handler 函数上方写 Go 注释，再由 swag init 扫描生成 docs/swagger.json。Buffalo 的 buffalo.Context 不影响该流程，只要 handler 是标准函数签名即可。
Buffalo框架 1.0.1 版本源码包下载，适合需要错误处理改进、依赖更新、render.Download 注释和 request logger 调整的 v1 项目。
- 在
actions/users.go的UsersCreate函数前加注释块，必须包含@Summary、@Param、@Success、@Failure - 请求体需定义独立 struct（不能直接 bind
map[string]interface{}），并用json:标签声明字段，swag才能提取 schema - 执行
swag init -g actions/app.go（入口文件需含func main()调用，即main.go） - 生成的
docs/目录需手动挂载为静态路由：app.ServeFiles("/swagger/*x", http.Dir("./docs"))
避免踩坑：struct 字段名与 JSON key 必须一致
swaggo 解析 struct 时严格依赖 json: tag，而非字段名本身。若定义 Name string `json:"name"`，但注释里写 @Param name body string true "用户名"，生成的 schema 中字段仍叫 name；但如果字段是 Name string 且无 tag，swag 会导出 Name（首字母大写），导致前端收到 {"Name": "xxx"} 而非预期的 {"name": "xxx"}。
- 所有用于 API 输入/输出的 struct 必须显式声明
json:tag，且值小写 - 嵌套 struct 同样适用，
swag会递归展开，但不支持匿名字段内联（如type User struct { Person }中的Person字段不会自动扁平化） - 切片字段如
Roles []string `json:"roles"`会被正确识别为 array of string，无需额外注释
生产环境文档路径必须带版本前缀
不要把 Swagger UI 暴露在根路径如 /swagger。Buffalo 的路由分组机制可帮你隔离文档入口，例如：
apiV1 := app.Group("/api/v1")
apiV1.ServeFiles("/docs/*x", http.Dir("./docs"))
这样访问地址变成 http://localhost:3000/api/v1/docs/index.html，与真实 API 版本对齐。否则当 v2 上线后，旧版文档仍挂在 /swagger 下，容易造成混淆。同时注意：该路由必须放在所有 app.Resource() 或 app.GET() 注册之后，否则可能被更宽泛的通配规则拦截。
