Documenting REST APIs without specs can be a tedious, error-prone task — especially if you’re working with legacy systems or third-party services that offer no official documentation. mitmproxy2swagger tackles this pain point by turning raw network captures into OpenAPI 3.0 specifications, saving you from manually writing hundreds of endpoint definitions.
automated OpenAPI 3.0 specification generation from mitmproxy and HAR captures
mitmproxy2swagger is a Python command-line tool designed to reverse-engineer REST APIs by processing network traffic captures. It supports input from mitmproxy flow dumps as well as browser HAR exports, making it versatile for different debugging and inspection workflows.
Under the hood, the tool implements a two-pass workflow: the first pass scans the captured traffic to discover endpoint paths and produces an initial, editable OpenAPI YAML schema. This schema includes “ignore:” prefixes for paths that might be irrelevant, giving developers an easy way to mark and exclude noise.
After manually refining the schema to remove or adjust these ignored paths, the second pass generates detailed endpoint descriptions, including parameters and request/response schemas. This human-in-the-loop approach strikes a tradeoff between fully automated spec generation and ensuring quality by letting the developer curate what gets documented.
The tool also supports incremental schema merging, so you can combine multiple captures over time to build a comprehensive API spec. Optional example data injection is available with the --examples flag, which enriches the generated spec with real request and response samples.
Built with modern Python tooling, mitmproxy2swagger uses Poetry for dependency and packaging management, pytest for testing, and pre-commit hooks for code quality enforcement. This indicates a well-maintained codebase adhering to best practices.
a human-in-the-loop two-pass discovery workflow balancing automation and control
What distinguishes mitmproxy2swagger is its two-pass approach to schema generation. Many tools in the API reverse-engineering space attempt fully automated spec generation, which often produces noisy or incomplete results.
Here, the first pass acts as a discovery phase that identifies potential endpoints and labels some as ignorable with prefixes. This initial YAML output is meant for manual editing — the developer reviews and prunes the schema, removing irrelevant or noisy paths. This step is essential because network captures often contain background or unrelated traffic that would pollute an API spec.
After curation, the second pass enriches the schema with detailed endpoint documentation, including request and response bodies, headers, and parameter types. This split workflow reduces guesswork and false positives compared to a single-pass automated tool.
The incremental schema merging feature is also worth noting. If you capture traffic from multiple sessions or different parts of an API, mitmproxy2swagger can merge these partial schemas into one evolving OpenAPI document. This aligns well with real-world workflows where API discovery is iterative.
The tradeoff is clear: the tool requires manual intervention between passes, so it’s not one-click magic. But in practice, this human-in-the-loop model improves the quality and usability of the generated specs.
quick start
First you will need python3 and pip3.
$ pip install mitmproxy2swagger
With the tool installed, you can generate an initial schema from a mitmproxy flow or HAR file, then edit the YAML to remove ignored prefixes before running the second pass to produce the final OpenAPI spec.
verdict
mitmproxy2swagger fits a specific but common developer need: documenting REST APIs when no specs exist or official docs are lacking. Its two-pass, human-in-the-loop workflow is a practical compromise that balances automation with the quality control developers require.
It’s not a fully automatic spec generator, so expect to spend some time curating and refining the initial output. But this manual step is actually a safeguard against noise and inaccuracies that plague fully automated tools.
For teams reverse-engineering APIs from network captures or debugging undocumented endpoints, mitmproxy2swagger offers a solid foundation to build OpenAPI 3.0 specs without starting from scratch.
The Python codebase is modern and well-maintained, making it straightforward to extend or integrate into existing workflows. Overall, it’s worth trying if you often deal with undocumented REST APIs or want to bootstrap API documentation from live traffic captures.
## Related Articles
- [hermes-hudui: a TypeScript web UI for interacting with the Hermes AI agent](https://ramdi.fr/github-stars/hermes-hudui-a-typescript-web-ui-for-interacting-with-the-hermes-ai-agent/) — hermes-hudui provides a TypeScript-based web UI to interact with the Hermes AI agent, offering real-time data visualizat
- [nh: a Rust-based unified CLI for the Nix ecosystem with enhanced search and ergonomics](https://ramdi.fr/github-stars/nh-a-rust-based-unified-cli-for-the-nix-ecosystem-with-enhanced-search-and-ergonomics/) — nh is a Rust CLI tool consolidating Nix, NixOS, and Home Manager commands with improved ergonomics, speed, and Elasticse
- [Pydoll: Async-native Chromium automation with typed extraction for web scraping](https://ramdi.fr/github-stars/pydoll-async-native-chromium-automation-with-typed-extraction-for-web-scraping/) — Pydoll is a Python library for Chromium automation using Chrome DevTools Protocol. It offers async-native APIs and Pydan
- [Ollama: a unified CLI and API platform for local large language models](https://ramdi.fr/github-stars/ollama-a-unified-cli-and-api-platform-for-local-large-language-models/) — Ollama simplifies running and managing open-source large language models locally with a unified CLI and REST API, suppor
- [httpie/cli: A human-friendly command-line HTTP client for API interaction](https://ramdi.fr/github-stars/httpie-cli-a-human-friendly-command-line-http-client-for-api-interaction/) — HTTPie CLI offers a simple, readable way to interact with HTTP APIs via command line, with built-in JSON support and col
---
**→ GitHub Repo:** [alufers/mitmproxy2swagger](https://github.com/alufers/mitmproxy2swagger) ⭐ 9,456 · HTML