技能介绍

问题场景

当一个 API 已经在线上运行，但团队手里没有正式合同时，前端、测试、文档和 Mock 服务往往只能围绕请求路径和示例响应来猜测接口形状。这种“猜测式联调”很容易在字段名、必填参数、错误码和响应结构上留下盲区，导致联调成本高、回归覆盖不足，也让后续生成客户端或运行契约测试变得不可靠。

工作方式

该技能把“先有真实流量、再补出合同”的路径拆成可执行步骤：

捕获流量：通过 mitmproxy 记录目标服务的请求与响应，或使用浏览器 DevTools 导出的 HAR 文件。
转换为 OpenAPI：调用 mitmproxy2swagger 将 mitmproxy 流量或 HAR 导出转换为初步的 OpenAPI 文档。
供下游使用：输出的规范可以交给代理继续优化、验证，也可直接用于生成客户端、模拟器、测试或可审查的接口文档。

适用边界与注意点

转换结果更像一份可编辑的起点，而不是自动等于生产级契约。捕获到的流量通常只反映已经触发过的路径、方法和字段；未访问的端点、低频分支、鉴权失败场景可能不会出现在规范中。建议在录制时尽量覆盖关键业务流程，保留请求头、查询参数和请求体示例，并在生成后检查方法、路径参数、响应码与真实服务是否一致。

还要注意输入流量的质量：一次残缺的请求样本可能被固化成默认示例，后续再修正就会增加返工成本。对敏感字段、内部调试字段或临时行为，应结合代码与需求补充说明，必要时在 OpenAPI 中增加 description、examples 或 x- 扩展，而不是默认所有捕获内容都代表长期接口承诺。同时需要校验上游 README 中的使用限制与输出兼容性，避免把初步规范直接当作最终交付物。