mitmproxy2swagger

https://user-images.githubusercontent.com/5400940/168086818-c48f60ab-3f95-42eb-b435-c8b1a6326b81.mp4

一个用于自动将 mitmproxy 捕获转换为 OpenAPI 3.0 规范的工具。这意味着您只需运行应用程序并捕获流量，即可自动逆向工程 REST API。

🆕 新功能！

新增对从浏览器开发者工具导出的 HAR 文件的支持。有关更多详细信息，请参阅 用法 - HAR。

安装

首先你需要安装 python3 和 pip3。

$ pip install mitmproxy2swagger
# ... 或 ...
$ pip3 install mitmproxy2swagger
# ... 或 ...
$ git clone [email protected]:alufers/mitmproxy2swagger.git
$ cd mitmproxy2swagger
$ docker build -t mitmproxy2swagger .

然后克隆仓库并根据下面的示例运行 mitmproxy2swagger。

用法

Mitmproxy

要通过检查 HTTP 流量来创建规范，您需要：

1. 使用 mitmproxy 工具捕获流量。我个人推荐使用 mitmweb，它是 mitmproxy 内置的 Web 界面。

   root@kitploit:~

   $ mitmweb
   Web server listening at http://127.0.0.1:8081/
   Proxy server listening at http://*:9999
   ...
   

   重要提示：

   要配置客户端使用 mitmproxy 暴露的代理，请查阅 mitmproxy 文档 获取更多信息。

2. 将流量保存为流文件。

   在 mitmweb 中，您可以通过使用“文件”菜单并选择“保存”来执行此操作：

   

3. 运行 mitmproxy2swagger 的第一遍：

   root@kitploit:~

   $ mitmproxy2swagger -i <mitmproxy_flow路径> -o <输出模式文件路径> -p <api前缀>
   # ... 或 ...
   $ docker run -it -v $PWD:/app mitmproxy2swagger mitmproxy2swagger -i <mitmproxy_flow路径> -o <输出模式文件路径> -p <api前缀>
   

   请注意，您可以使用现有模式，在这种情况下，现有模式将用新数据扩展。您还可以多次运行它，使用不同的流捕获，捕获的数据将被安全合并。

   <api前缀> 是您想要逆向工程的 API 的基础 URL。您需要通过观察 mitmproxy 中的请求来获取它。

   例如，如果应用程序发出了如下请求：

   root@kitploit:~

   https://api.example.com/v1/login
   https://api.example.com/v1/users/2
   https://api.example.com/v1/users/2/profile
   

   可能的前缀是 https://api.example.com/v1。

4. 运行第一遍后，模式文件中应该会创建一个如下部分：

   root@kitploit:~

   x-path-templates:
     # 移除 ignore: 前缀以生成包含其URL的端点
     # 靠前的行优先级更高，匹配是贪婪的
     - ignore:/addresses
     - ignore:/basket
     - ignore:/basket/add
     - ignore:/basket/checkouts
     - ignore:/basket/coupons/attach/{id}
     - ignore:/basket/coupons/attach/104754
   

HAR

1. 从浏览器开发者工具捕获并导出流量。

   在浏览器开发者工具中，转到“网络”选项卡，然后单击“导出 HAR”按钮。

   

2. 按照与 mitmproxy 转储相同的方式继续操作。mitmproxy2swagger 会自动检测 HAR 文件并进行处理。

示例输出

参见 示例。您会在那里找到一个生成的模式文件和一个包含生成文档的 HTML 文件（通过 redoc-cli 生成）。

查看 生成的 HTML 文件。

开发与贡献

此项目使用：

• uv 用于依赖管理
• prek 用于代码格式化和 lint
• pytest 用于单元测试

安装依赖：

uv sync

运行 linter：

uv run prek run --all-files

安装 prek 钩子：

uv run prek install

运行测试：

uv run pytest

带有覆盖率运行测试：

uv run pytest --cov=mitmproxy2swagger

许可证

MIT