Proxyman vs mitmproxy：从抓取的流量生成 OpenAPI

你已经有一个 API，但它的文档缺失或已经过时。你能在应用中看到这些请求，但要手动编写每一个路径、参数和响应，可能需要花费数小时。

HTTP 调试工具可以帮上忙。它能抓取应用发出的真实请求。下一步，就是把这些请求转换为人和工具都能理解的 OpenAPI 文档。

mitmproxy 和 Proxyman 都可以参与这一流程。主要区别在于所需的步骤数量。使用 mitmproxy 时，常见做法需要借助一个单独的命令行工具；而 Proxyman 则在应用内置了 OpenAPI 导出功能。

什么是 OpenAPI？

OpenAPI 是一种用于描述 REST API 的标准格式。它可以告诉人和软件以下信息：

• 有哪些可用的 URL
• 使用哪些 HTTP 方法，例如 GET、POST 或 DELETE
• 接受哪些查询参数或路径参数
• 请求体的结构是什么样的
• 服务器可能返回什么内容
• 使用了哪些状态码

例如，你的应用可能会发送这样的请求：

GET https://api.example.com/users/123

OpenAPI 文档可以把该请求描述为类似 /users/{id} 的路径，也可以描述服务器返回的 JSON 数据。

OpenAPI 文件通常使用 YAML 或 JSON 编写。你可以用 Swagger Editor 等工具打开它们，用它们创建 API 文档，或从中生成客户端代码。

为什么要根据真实流量生成 OpenAPI？

最好的 API 文档应当与 API 源代码一同编写和维护。然而在实际项目中，文档往往不完整、已过时，或者根本无从获取。

在以下情况下，根据抓取的流量生成初稿会很有帮助：

• 你正在维护一个遗留 API
• 你加入的项目文档很少
• 你需要了解自己的移动端或 Web 应用所使用的 API
• 你想为 QA 提供一份真实的端点列表
• 你想将当前 API 与旧版文档进行对比
• 你需要在编写更完善的文档之前，先有一个快速的起点

抓取的流量提供了真实的示例。它展示了在那次会话中，应用发送了什么，服务器又返回了什么。

当前使用 mitmproxy 的方案

mitmproxy 是一款免费且功能强大的拦截代理。它可以抓取 HTTP、HTTPS 和 WebSocket 流量。对于喜欢终端工具、Python 和自动化工作流的开发者来说，它是一个很好的选择。

mitmproxy 的主界面并未提供简单的内置 OpenAPI 导出功能。常见做法是使用独立的社区项目 mitmproxy2swagger。

通常的工作流程如下：

1. 安装并启动 mitmproxy 或 mitmweb。
2. 配置你的应用或设备，使其流量经过该代理。
3. 抓取你需要的 API 请求。
4. 将抓取的流量保存为 mitmproxy flow 文件或 HAR 文件。
5. 安装 mitmproxy2swagger 及其所需的 Python 环境。
6. 运行命令，并指定输入文件、输出文件以及 API URL 前缀。
7. 打开第一次生成的 YAML 结果，并选择要包含的已检测路径。
8. 再次运行命令，生成更完整的 OpenAPI 文档。

第一条命令可能如下所示：

mitmproxy2swagger \
  -i capture.flow \
  -o api-schema.yaml \
  -p https://api.example.com/v1

第一遍运行会找出可能的 API 路径。随后，你需要检查 YAML 文件，从想要保留的路径中删除 ignore:，并修正路径参数。之后再次运行该工具。可选参数可以添加示例或请求头。

这一方案很灵活，也很适合放进脚本或可重复执行的构建流程中。但它由多个部分组成，每个部分都需要单独处理。

当前方案有哪些难点？

问题并不在于 mitmproxy 无法抓取流量，它完全可以。难点在于从抓取到最终 OpenAPI 文件之间的所有步骤。

1. 需要使用多个工具

你需要先用 mitmproxy 抓取流量，然后再安装并运行另一个项目来生成 OpenAPI。每个工具都有各自的配置方式、命令、版本和文件格式。

对于有经验的命令行用户来说，这可能没什么问题。但对于新手开发者或 QA 测试人员来说，这会拖慢一项本应很简单的任务。

2. 需要两遍执行的工作流程

第一次生成的文件并不是最终结果。你需要打开它、选择路径、编辑其中的值，然后再运行一次命令。

这一额外的检查确实有用，但如果你只想根据几个选定的请求快速生成一份文档，它可能会让人意外。

3. 完整抓取的内容干扰信息多

浏览器或移动应用可能会调用统计分析、图片服务器、功能开关、身份验证服务以及许多其他主机。如果导出整个会话，生成的 OpenAPI 结果可能会包含远超你所需 API 的内容。

如果能先查看请求，并在导出前只选中有用的部分，就会轻松得多。

4. 示例中可能包含私密数据

真实流量之所以有用，是因为它包含真实的值。但这些值也可能带来风险。示例中可能包含令牌、电子邮件地址、内部 URL 或用户 ID。

在将输出内容提交到 Git、上传到文档站点或分享给他人之前，请务必先检查。

使用 Proxyman 的更简单方案

Proxyman 的 macOS 应用内置了 OpenAPI 导出功能。你只需抓取流量、选择所需的请求，然后将其导出为 OpenAPI YAML 或 HTML。

无需安装额外的转换工具，也无需运行第二条命令。

第 1 步：抓取 API 流量

下载并打开最新版本的 Proxyman for macOS。按照应用内显示的设置说明，安装并信任 Proxyman 证书。

然后使用你的网站、模拟器或移动应用，执行你想要记录的操作。例如，打开个人资料页面，抓取加载用户信息的请求。

请确保 Proxyman 能够看到解密后的请求和响应。

为了获得干净的结果，每次只抓取一个小的用户操作流程。开始之前，你可以先清空当前会话。

第 2 步：选择有用的请求

在主表格中找到 API 主机，选中属于你文档范围的请求。

无需选中所有请求。图片、统计分析及其他不属于 API 的服务都可以排除在外。

如果同一个端点出现多次，可以先从一个明确的成功响应开始。之后，当其他示例展示出不同的请求或响应结构时，再补充更多示例。

第 3 步：导出 OpenAPI

右键点击选中的请求，然后选择：

Export → OpenAPI → OpenAPI YAML

选择文件的保存位置。

以上就是完整的导出流程。Proxyman 会根据你选中的请求和响应生成 OpenAPI 文件。

第 4 步：检查 YAML 文件

在 Swagger Editor 或你常用的代码编辑器中打开 YAML 文件。检查路径、方法、参数和 schema 是否合理。

生成的文档只是一个起点。真实流量只反映了某一次会话中发生的情况，它无法得知所有可能的错误响应，也无法得知服务器支持的每一个可选值。

第 5 步：按需导出易读的 HTML

如果同事只需要阅读 API，可以改为导出 HTML：

Export → OpenAPI → OpenAPI HTML

HTML 适合快速查看或私下交接。如果你打算编辑文档、进行校验，或将其与其他 OpenAPI 工具配合使用，YAML 会更合适。

Proxyman 与 mitmproxy 的 OpenAPI 功能对比

mitmproxy 依然是一款强大的工具。如果你已经在用 Python 自动化抓取流量，它的工作流程可能非常适合你的项目。如果你希望检查某次会话，并且无需先搭建命令行流程就能生成一份有用的文档，那么 Proxyman 会更有帮助。

分享前检查生成的文档

无论使用哪种工具，都请检查以下几点：

1. 移除敏感信息。 搜索令牌、Cookie、密码、私有请求头、电子邮件地址和个人数据。
2. 检查路径参数。 类似 /users/123 的路径可能需要改为 /users/{id}。
3. 补充缺失的响应。 你抓取的内容可能只包含 200，而没有 400、401、404 或 500。
4. 检查必填字段。 单个示例无法证明每个字段都是必填的。
5. 检查数据类型。 在某个响应中看起来像数字的值，实际上可能是字符串类型的 ID。
6. 补充身份验证信息。 描述预期的身份验证方式，但不要复制真实的密钥。
7. 使用清晰的命名和说明。 生成的 schema 仍然需要人工补充解释。
8. 校验文件。 在 OpenAPI 编辑器中打开，并修复所有警告。

总结

根据流量生成 OpenAPI 可以节省大量时间，尤其是在缺少原始文档的情况下。mitmproxy 可以借助单独的转换工具和命令行工作流来完成这项工作。这种方式很灵活，但需要用户管理更多的步骤。

Proxyman 将基本流程集中在一个地方完成：抓取请求、选择有用的行，然后导出 OpenAPI YAML 或 HTML。对于希望快速获得文档、并计划事后再进行检查的开发者和 QA 团队来说，它是一个友好的起点。

延伸阅读

• 阅读 Proxyman OpenAPI 导出文档
• 参考详细的 生成 OpenAPI YAML 教程
• 了解如何抓取 iPhone 或 iPad 的 HTTPS 流量
• 了解如何抓取 Android 模拟器的 HTTPS 流量
• 阅读 mitmproxy2swagger 项目指南