Turn Your Traffic Captures Into OpenAPI Specs With mitmproxy2swagger

You've probably been there: you're poking at a mobile app or a web client, watching requests fly by in mitmproxy, and you think, "I could write an OpenAPI spec for this, but it's going to take all afternoon." Instead of hand-transcribing endpoints one by one, mitmproxy2swagger takes those captured flows and generates an OpenAPI 3.0 specification for you.

What It Does

mitmproxy2swagger is a Python tool that converts mitmproxy captures into OpenAPI 3.0 specifications. The core idea is straightforward: you run the app you want to reverse-engineer, capture its HTTP traffic through mitmproxy, save that traffic to a flow file, and then feed the file to mitmproxy2swagger along with a base URL prefix. The tool reads the flow, finds the requests that match your prefix, and builds out a schema.

It works in two passes. The first pass creates a list of path templates in the schema file, each one prefixed with ignore: so nothing gets generated until you've had a say. You open the file in a text editor, strip the ignore: prefix from the paths you actually care about, and adjust any parameters to your liking. The second pass picks up your edits and generates the full endpoint descriptions. It's a nice bit of design because it keeps you in the loop rather than dumping a wall of guessed endpoints on your desk.

The tool also supports HAR files exported from browser DevTools, so if you'd rather capture traffic in Chrome or Firefox than set up a proxy, that's an option too.

Why It's Cool

• The two-pass workflow respects your judgment. Most code-generation tools assume they know best. This one hands you a draft list of paths and says, "here's what I found, tell me what matters." That's a small thing, but it makes the output much more useful in practice — you're not deleting half the spec after the fact.

• You can merge captures across sessions. The README notes you can run the tool multiple times with different flow captures, and the captured data will be safely merged. That's handy for APIs where different features live behind different flows — log in, browse, check out, and stitch the results together.

• It extends existing schemas. If you already have a partial OpenAPI spec, you can point the tool at it and it'll add new data rather than overwriting your work. That means you can grow a spec incrementally as you discover more of an API.

• Greedy path matching with precedence. The generated path template list is ordered, and lines closer to the top take precedence. That gives you a predictable way to control how ambiguous routes get matched — a detail that suggests someone actually used this on a real API with overlapping paths.

• It's installable in multiple ways. PyPI, the Arch Linux repos, or a Docker build from source. If you're on Arch, you can grab it from the official extra repo. Small touch, but nice.

How to Try It

You'll need Python 3 and pip. Install it:

pip install mitmproxy2swagger

Or if you'd rather build from source:

git clone [email protected]:alufers/mitmproxy2swagger.git
cd mitmproxy2swagger
docker build -t mitmproxy2swagger .

Then capture some traffic. The README recommends mitmweb, the web interface bundled with mitmproxy:

mitmweb

This starts a web server at http://127.0.0.1:8081/ and a proxy at port 9999. Configure your client to use the proxy (check the mitmproxy docs for that part), exercise the app, then save the traffic via the File menu in mitmweb.

Now run the first pass:

mitmproxy2swagger -i <path_to_mitmproxy_flow> -o <path_to_output_schema> -p <api_prefix>

The api_prefix is the base URL of the API — say https://api.example.com/v1 if you're seeing requests like https://api.example.com/v1/users/2. You'll have to figure that out by watching the requests.

Open the generated schema, remove ignore: from the paths you want, then run the same command again to generate the endpoint descriptions. There's also an optional --examples flag on the second pass.

Full details and the rest of the usage notes are in the repository.

Final Thoughts

If you regularly need to document undocumented APIs — whether for integration work, testing, or just understanding what a client is doing — mitmproxy2swagger saves you the tedious part of the job. It's not magic; you still need to curate the path list and sanity-check the output, and the quality of the generated spec depends on how representative your capture is. But it turns an afternoon of manual spec-writing into a couple of passes over a YAML file, and the merge-and-extend behavior means the effort compounds over time. Worth a look if mitmproxy is already in your toolkit.

Follow @githubprojects for more developer tools and open source projects.