三步把抓包变成接口文档：mitmproxy2swagger API 逆向工程实战教程-平芜编程栈

三步把抓包变成接口文档：mitmproxy2swagger API 逆向工程实战教程

【免费下载链接】mitmproxy2swaggerAutomagically reverse-engineer REST APIs via capturing traffic项目地址: https://gitcode.com/GitHub_Trending/mi/mitmproxy2swagger

拿到一个只有安装包、没有接口文档的第三方 App，周五前却要把接口说明交给同事？mitmproxy2swagger 做的事情很直白：你照常运行 App 并保存抓包文件，它负责把流量自动转成 OpenAPI 3.0 规范，路径、方法、参数、请求与响应结构都能从流量里推断出来。

没文档的 API，逆向起来有多费劲

手动逆向一个 REST 接口，基本流程是：打开抓包工具 → 逐条翻请求 → 认出哪些 URL 片段是参数 → 对照响应体猜字段结构 → 写进文档。接口多、参数乱的时候，这套动作既慢又容易漏。

mitmproxy2swagger 换了个思路：让工具直接"看"流量。它支持两种输入源——mitmproxy 的.flow抓包文件和浏览器 DevTools 导出的.har文件，输出则是可以直接喂给 Swagger UI、Redoc 这类渲染器的 YAML 规范。

📦 安装 mitmproxy2swagger：pip 与 Docker 两条路

本机有 python3 的话，执行下面这条命令就能装上，装完后会得到一个全局可用的mitmproxy2swagger命令：

pip install mitmproxy2swagger

不想动本机 Python 环境，可以用 Docker 镜像。先拉取仓库并构建，会得到一个名为mitmproxy2swagger的本地镜像：

git clone https://gitcode.com/GitHub_Trending/mi/mitmproxy2swagger cd mitmproxy2swagger && docker build -t mitmproxy2swagger .

之后所有转换都通过容器执行，挂载当前目录即可读写文件：

docker run -it -v $PWD:/app mitmproxy2swagger \ mitmproxy2swagger -i cap.flow -o schema.yaml -p https://api.example.com/v1

📡 两种抓取保存方式：mitmweb flow 文件与浏览器 HAR

App 或任意走代理的流量，用 mitmproxy 自带的 Web 界面最顺手。启动后会看到 Web 服务与代理服务的监听地址：

mitmweb

把客户端代理指向 mitmproxy 后正常操作目标应用，流量会实时列在页面里。操作完成后，在顶部 File 菜单选择 Save，即可把会话落盘为一个.flow文件：

Web 端请求则完全不需要装代理。打开浏览器 DevTools 的 Network 面板，勾上 Preserve log，把功能点一遍，再点工具栏上的导出按钮，得到一个.har文件：

这两种文件格式不同，但转换阶段可以互换——工具会自动识别输入文件类型，识别不准时还能用-f flow或-f har手动指定。

从 flow 到 OpenAPI 文档：转换走查

整个转换分两轮执行，这是使用中最容易卡住的点，值得说清楚。

第一轮：生成路径清单。下面的命令会读入抓包文件，输出一份"骨架"规范：

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

-p是这批请求的公共前缀，去抓包里找 URL 的公共部分即可。跑完后，schema.yaml里会出现一段x-path-templates，把观察到过的路径全部列出来，并默认全部挂上ignore:前缀：

x-path-templates: - ignore:/users/{id} - ignore:/basket/add - ignore:/login

注意排序规则：靠上的行优先匹配，匹配是贪婪的，所以宽泛的模板要放前面。

然后用编辑器打开文件，把想生成文档的路径前面的ignore:删掉，顺手核对一下{id}这类参数占位符是否合理。

第二轮：真正生成端点描述。命令不变，可加--examples附上真实样例：

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

这一轮会读取你编辑过的ignore:开关，为选中的路径补齐方法、参数和响应结构。两个容易踩的坑：--examples会把请求体、响应体里的真实数据（token、个人信息等）写进规范，对外发布前记得清理；另外已有端点的描述不会被覆盖，想重新生成得先手动删掉旧内容。

⚙️ mitmproxy2swagger 参数速查表

参数	什么时候用
`-i`/`--input`	指定输入，支持`.flow`与`.har`，自动识别
`-o`/`--output`	指定输出的 YAML；文件已存在时是"追加扩展"而非覆盖
`-p`/`--api-prefix`	API 基础前缀，从抓包的 URL 公共部分推断
`--examples`	附请求/响应示例，⚠️ 可能带入敏感数据
`--headers`	附请求/响应头，⚠️ 可能暴露认证信息，默认不附
`--param-regex`	自定义路径参数识别规则，默认只认`[0-9]+`
`-f`/`--format`	强制按`flow`或`har`解析，跳过自动识别

当路径里的参数不是纯数字时，--param-regex就是刚需。比如参数是 UUID，默认规则认不出来，可以这样指定：

mitmproxy2swagger -i capture.flow -o schema.yaml \ -p https://api.example.com \ --param-regex "[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}"

进阶：增量合并与源码结构

多批次抓包不用重头再来。今天抓一批、明天再抓一批，甚至 App 流量和浏览器 HAR 混着来，只要-o指向同一份文件反复执行，数据会安全合并进已有规范——这对"边测边补文档"的团队尤其友好。

想理解实现，核心逻辑都在 mitmproxy2swagger/ 目录：mitmproxy2swagger.py 负责命令行与流程调度，mitmproxy_capture_reader.py 解析 flow 文件，har_capture_reader.py 解析 HAR，swagger_util.py 负责规范生成。想确认最终效果，可以浏览仓库里渲染好的示例文档 example_outputs/lisek-static.html。