mitmproxy2swagger

mitmproxy2swagger is a command-line tool that watches the network traffic going in and out of an app and automatically builds a written description of the API that app is using. An API description in this context is a structured document that spells out what requests the app makes, what data it sends, and what it expects back. The format it produces is called OpenAPI 3.0, which many other developer tools can read to generate documentation or tests.

The typical scenario is: you have a mobile app or a web service, and you want to understand how it communicates with its backend server, but you do not have access to the backend's source code or documentation. You run a traffic-capture tool called mitmproxy alongside the app, use the app normally for a while, then save that recorded traffic to a file. You feed that file into mitmproxy2swagger, and it figures out the URL patterns, HTTP methods, and data structures on its own.

The process runs in two passes. The first pass produces a draft file listing every URL path it detected, each marked with an ignore prefix by default. You open that file in a text editor, remove the ignore prefix from the endpoints you actually care about, and save it. The second pass reads the edited file and fills in the full endpoint descriptions. You can optionally include example request and response data, though the README notes that this may expose sensitive information like tokens or passwords.

Beyond mitmproxy captures, the tool also accepts HAR files, which are traffic exports you can get directly from the Network tab in a browser's developer tools. This makes it usable without any proxy setup at all.

Installation is through pip, the standard Python package installer, or via Docker if you prefer a contained environment. The tool is open source under the MIT license and includes a test suite and code formatting checks for contributors.