mitmproxy2swagger

mitmproxy2swagger is a command-line tool that transforms HTTP traffic captures (from mitmproxy flow files or browser DevTools HAR exports) into OpenAPI 3.0 (Swagger) specifications. This enables developers to quickly reverse-engineer REST APIs by merely running an application and logging its network requests, rather than manually examining endpoints and parameters. ## Key Capabilities - **Input formats**: Accepts mitmproxy flow files (`.mitm` via mitmweb/mitmproxy) and HAR files (auto-detected). - **Two-pass workflow**: First pass generates a template with all discovered paths; users edit the template to select which endpoints to include and adjust path parameters (e.g., replace dynamic IDs with `{id}` placeholders). Second pass fills in detailed request/response schemas, combining data from multiple capture sessions without overwriting existing content. - **Extensible schemas**: Can merge new data into an existing schema file, allowing incremental improvement across captures. - **Optional data enrichment**: Flags `--examples` and `--headers` include sample payloads and header information (with a warning about potentially sensitive data). - **Output format**: Generates YAML files compatible with OpenAPI 3.0, usable with documentation tools like Redoc. ## Typical Usage 1. Capture HTTP traffic (e.g., with `mitmweb`, then save flow file). 2. Run `mitmproxy2swagger -i flow.mitm -o schema.yaml -p https://api.example.com/v1` to create initial template. 3. Edit schema.yaml: remove `ignore:` prefixes from desired paths. 4. Re-run the command to generate full endpoint definitions. ## Technical Details - Written in Python, installable via pip or run via Docker. - Available on PyPI and Arch Linux repositories. - Development uses uv, prek (linting), and pytest for testing; contributions welcome. - MIT licensed. ## Example Use Case Given an app making requests to `https://api.example.com/v1/login`, `/users/2`, and `/users/2/profile`, the tool would suggest `https://api.example.com/v1` as the prefix, then guide the user to define path templates like `/users/{id}` and `/users/{id}/profile`. For a practical demonstration, see the included `example_outputs/` directory with a generated schema and a rendered HTML documentation example.