Buffalo注册Swagger需用buffalo.WrapHandler桥接http.Handler，路径设为"/swagger/*any"，并确保docs包被_导入及swag注释位于可扫描的handler上。
ginSwagger.WrapHandler 一键封装。你不能直接调用 app.GET("/swagger/*any", ...) 并传入一个 handler —— Buffalo 的路由系统是基于 App.Routes() 构建的，中间件和 handler 必须符合其 buffalo.Handler 类型签名，而 http-swagger 提供的是标准 http.Handler。
所以，**Buffalo 注册 Swagger 路由的本质，是把标准 http.Handler “桥接”进 Buffalo 的路由生命周期中**。这需要手动包装，且必须注意请求上下文（buffalo.Context）和原始 http.ResponseWriter/*http.Request 的转换。
Buffalo 中无法直接使用 http-swagger.Handler
常见错误现象是：写类似 app.GET("/swagger/*any", swaggerFiles.Handler)，结果报错 cannot use swaggerFiles.Handler (type http.Handler) as type buffalo.Handler。这是因为 buffalo.Handler 签名是 func(context.Context) error，而 http.Handler 是 func(http.ResponseWriter, *http.Request) —— 类型不兼容，不能混用。
必须用 buffalo.WrapHandler 包装标准 http.Handler
buffalo.WrapHandler 是官方提供的适配器，用于把任意 http.Handler 转成 buffalo.Handler。它会自动提取 http.ResponseWriter 和 *http.Request 并传给下游 handler，同时保留 buffalo.Context 的可访问性（通过 c.Response().Writer 和 c.Request()）。
开箱即用的技能链路由引擎。13 条预定义链覆盖搜索、开发、审查、MLOps、法律、创意等场景，三层路由架构（触发词→SAD反馈→DAG编排），recall@10=96.97%。配置驱动（chains.yaml），零代码扩展。pip install skill-weave-chains 一键安装。
- 确保已安装
github.com/swaggo/http-swagger - 在
app.go或路由初始化处 import："github.com/swaggo/http-swagger"和"github.com/gobuffalo/buffalo" - 在
app.Routes()内添加：app.GET("/swagger/*any", buffalo.WrapHandler(httpSwagger.WrapHandler())) - 注意路径必须带
/*any，否则子路径（如/swagger/index.html）无法匹配
生成 docs 后，docs.go 必须被 main 包 import
swag init 生成的 docs/docs.go 文件里定义了 docs.SwaggerInfo 和 swaggerFiles 变量。如果没被任何包 import，Go 编译时会丢弃整个包（包括嵌入的静态资源），导致访问 /swagger/ 时返回 404 或空页面。
- 在
main.go顶部显式 import：_ "your-project-name/docs"（路径替换成你实际的模块路径） - 不要漏掉下划线
_，因为docs.go只做包级初始化，不导出函数 - 若用 Go Modules，确保
go.mod中模块名与 import 路径一致，否则docs包无法解析
Swag 注释必须在 buffalo.App 初始化前完成扫描
swag init 是静态分析工具，只读取源码注释，不执行代码。但 Buffalo 的 app.New() 会触发中间件、plugin、甚至部分 handler 初始化逻辑 —— 如果你的 @Summary 或 @Router 注释写在某个 plugin 的初始化函数里（比如自定义 middleware 中动态注册的 handler），swag 工具根本看不到它们。
- 所有 API 注释必须写在
actions/*.go或明确被main.go引用的 handler 函数上 - 避免把 handler 定义在闭包、匿名函数或延迟加载的插件中
- 执行
swag init -g actions/app.go（指定入口）比盲目swag init更可靠，防止漏扫
dev 模式默认启用 https:// 重定向（尤其在 app.Serve() 启动时），而 http-swagger 默认生成的 swagger.json 里的 schemes 是 ["http"]。如果你用 HTTPS 访问 /swagger/，但文档里声明只支持 HTTP，Swagger UI 会拒绝发起请求 —— 控制台报 Failed to load API definition，且不提示具体原因。这时得手动在 docs/docs.go 里改 SwaggerInfo.Schemes，或者用 swag init -s http,https 重新生成。 
