摘要
一句话总结
mitmproxy2swagger 是一款将 mitmproxy 抓取的网络流量或 HAR 文件自动转换为 OpenAPI 3.0 规范的开源工具，主要用于 REST API 的逆向工程与文档快速生成。
核心要点
- 开源与规范：基于 MIT 协议开源，输出标准的 OpenAPI 3.0 规范（Schema）。
- 多输入源支持：支持解析 mitmproxy 导出的 flow 文件，以及浏览器开发者工具导出的 HAR 格式文件。
- 两步生成机制：采用半自动化控制，首次运行生成带有
ignore:前缀的路径模板，用户需手动移除前缀并调整参数后，二次运行才生成最终的 API 端点。 - 数据安全合并：支持对同一 Schema 文件多次输入不同的抓取数据，工具会将新捕获的数据安全合并到现有规范中。
- 附加信息提取：通过
--examples和--headers参数，可将请求/响应的示例数据及请求头信息直接写入规范文档。 - 运行环境：支持通过 Python (pip) 原生安装运行，或通过 Docker 容器化部署。
风险与不足
- 敏感信息泄露风险：使用
--examples或--headers参数时，可能会导致 Token、密码、个人隐私等敏感数据被直接写入生成的 Schema 文件中。 - 端点覆盖限制：在二次运行生成端点描述时，工具不会自动覆盖已存在的端点描述；若需重新生成或覆盖，必须手动删除旧描述。
功能与定位
mitmproxy2swagger 是一个自动化工具，旨在将 mitmproxy 抓取的网络流量转换为 OpenAPI 3.0 规范。用户只需运行应用程序并抓取其网络流量，即可利用该工具自动逆向工程 REST API 并生成对应的 API 文档。
典型使用场景
- 对未提供官方文档的应用程序进行 REST API 逆向工程。
- 基于浏览器或客户端的实际网络请求，快速生成或补全 OpenAPI/Swagger 接口文档。
核心功能
- 流量解析与转换：支持读取 mitmproxy 导出的 flow 文件，并将其转化为 OpenAPI 3.0 规范（Schema）。
- HAR 文件支持：自动识别并处理从浏览器开发者工具（DevTools）导出的 HAR 格式流量文件。
- 数据安全合并：支持对同一个 Schema 文件多次运行不同的抓取数据，工具会将新捕获的数据安全地合并到现有规范中。
- 示例与请求头提取：提供附加参数（
--examples和--headers），可将请求和响应的示例数据及请求头信息直接写入生成的规范中。
特色与差异点
- 两步生成机制（半自动化控制）：
- 首次运行会生成包含所有捕获路径的模板列表（默认带有
ignore:前缀）。 - 用户可以手动介入，通过文本编辑器移除特定路径的
ignore:前缀并调整路径参数，从而精准控制最终需要生成的 API 端点。
- 首次运行会生成包含所有捕获路径的模板列表（默认带有
- 多环境运行：支持通过 Python (pip) 原生安装运行，也支持通过 Docker 容器化运行。
使用方式概览
- 环境准备：通过
pip install mitmproxy2swagger安装，或使用 Docker。 - 抓取流量：使用 mitmproxy（推荐使用自带 Web 界面的 mitmweb）或浏览器开发者工具抓取目标应用的 HTTP 流量，并保存为 flow 文件或 HAR 文件。
- 首次解析：运行 mitmproxy2swagger 命令，指定输入流量文件、输出 Schema 路径以及目标 API 的基础前缀（Base URL）。
- 编辑模板：打开生成的 Schema 文件，在
x-path-templates区域中，将需要生成的 API 路径前的ignore:前缀删除。 - 二次生成：再次运行相同的解析命令，工具会读取修改后的模板，正式生成 API 端点描述。
限制与注意事项
- 敏感信息风险：在使用
--examples或--headers参数时需格外谨慎，这可能会导致 Token、密码、个人隐私等敏感数据被写入到生成的 Schema 文件中。 - 端点覆盖限制：在二次运行生成端点描述时，工具不会自动覆盖已存在的端点描述。如果需要重新生成或覆盖，必须在运行前手动删除旧的描述。