alufers /mitmproxy2swagger

Automagically reverse-engineer REST APIs via capturing traffic

★ 9,732⑂ 385👁 25⑃ 192● 45▤ 20
HTMLCreated 2022-05-11
Download: uv migration, dependency updates, bugfixesuv-0.15.0 ↓0.15.02026-05-25
+5
Daily
9,732
stars
385
forks
25
watchers
192
prs
45
issues
20
releases

README

mitmproxy2swagger






A tool for automatically converting mitmproxy captures to OpenAPI 3.0 specifications. This means that you can automatically reverse-engineer REST APIs by just running the apps and capturing the traffic.

---

🆕 NEW!

Added support for processing HAR exported from the browser DevTools. See Usage - HAR for more details.

---

 Installation

First you will need python3 and pip3.

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


Then clone the repo and run mitmproxy2swagger as per examples below.

 Usage

 Mitmproxy

To create a specification by inspecting HTTP traffic you will need to:

1. Capture the traffic by using the mitmproxy tool. I personally recommend using mitmweb, which is a web interface built-in to mitmproxy.

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

   IMPORTANT

   To configure your client to use the proxy exposed by mitm proxy, please consult the mitmproxy documentation for more information.

2. Save the traffic to a flow file.

   In mitmweb you can do this by using the "File" menu and selecting "Save":

   !A screenshot showing the location of the "Save" option in the "File" menu

3. Run the first pass of mitmproxy2swagger:

   bash
   $ mitmproxy2swagger -i  -o  -p 
    ... or ...
   $ docker run -it -v $PWD:/app mitmproxy2swagger mitmproxy2swagger -i  -o  -p 
   

   Please note that you can use an existing schema, in which case the existing schema will be extended with the new data. You can also run it a few times with different flow captures, the captured data will be safely merged.

    is the base url of the API you wish to reverse-engineer. You will need to obtain it by observing the requests being made in mitmproxy.

   For example if an app has made requests like these:

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

   The likely prefix is https://api.example.com/v1.

4. Running the first pass should have created a section in the schema file like this:

   yaml
   x-path-templates:
      Remove the ignore: prefix to generate an endpoint with its URL
      Lines that are closer to the top take precedence, the matching is greedy
     - ignore:/addresses
     - ignore:/basket
     - ignore:/basket/add
     - ignore:/basket/checkouts
     - ignore:/basket/coupons/attach/{id}
     - ignore:/basket/coupons/attach/104754
   

   You should edit the schema file with a text editor and remove the ignore: prefix from the paths you wish to be generated. You can also adjust the parameters appearing in the paths.

5. Run the second pass of mitmproxy2swagger:

   bash
   $ mitmproxy2swagger -i  -o  -p  [--examples]
    ... or ...
   $ docker run -it -v $PWD:/app mitmproxy2swagger mitm

Top issues

Latest release

uv migration, dependency updates, bugfixes 0.15.0 2026-05-25
- Python 3.14 is the default version used in CI and docker container
  - Python 3.12 is the minimum supported Python version
  -  Upgraded mitmproxy from 11.0.2 to 12.2.3
  - Fix UnicodeEncodeError when saving swagger file on Windows — thanks @MrTheFall (212)
  - Fix flow files being misdetected as HAR when first bytes contain only printable characters (e.g. certificates) — thanks @kristiandueholm (215)
  - Fix path parameters being dropped when using --headers flag — thanks @matgoebl (216)
  - Fix AttributeError: 'str' object has no attribute 'decode' when processing HAR files with form

Snapshot: 2026-11-16T09:23:14Z · Data license Apache-2.0 · JSON