Stop Writing API Docs by Hand! mitmproxy2swagger Does It for You

Stop Writing API Docs by Hand! mitmproxy2swagger Does It for You

What if I told you that every hour you spend manually documenting REST APIs is an hour you could have spent actually building something? Here's the brutal truth: most developers are still writing OpenAPI specifications by hand, squinting at network requests, copying JSON payloads into YAML files, and praying they didn't miss a single required field. It's 2024, and we're still doing archaeology on our own APIs.

But what if you could simply run an app, capture its traffic, and watch as a complete, production-ready OpenAPI 3.0 spec materializes before your eyes? No more guessing parameter types. No more missed endpoints. No more outdated documentation that lies to your users.

Enter mitmproxy2swagger — the open-source secret weapon that's making manual API documentation obsolete. Created by alufers and already turning heads in the developer community, this tool doesn't just save time; it fundamentally reimagines how we reverse-engineer and document REST APIs. Whether you're dealing with a legacy API with zero documentation, a third-party service that won't share its specs, or an internal microservice that "someone will document someday," mitmproxy2swagger transforms captured HTTP traffic into pristine OpenAPI specifications. Automatically. Effortlessly. Insanely accurately.

Ready to never write another API doc by hand again? Let's dive deep into how this works — and why you need it in your toolkit today.

What is mitmproxy2swagger?

mitmproxy2swagger is a Python^{↗ Bright Coding Blog}-based command-line tool that bridges the gap between raw HTTP traffic and structured API documentation. At its core, it consumes network capture files — either from mitmproxy (the legendary interactive HTTPS proxy) or HAR files exported from browser DevTools — and emits fully compliant OpenAPI 3.0 specifications.

The project lives at github.com/alufers/mitmproxy2swagger and has gained serious traction for one simple reason: it solves a universal developer pain point with almost zero friction. The creator, alufers, built this tool on a deceptively simple insight — if an API is being used, its complete behavior is already encoded in the traffic it generates. Why manually transcribe what machines can observe directly?

Here's why it's trending right now:

• The API economy explosion: Every company is now an API company, but documentation remains the #1 developer complaint
• Legacy system modernization: Organizations are sitting on thousands of undocumented internal APIs that need cataloging
• Third-party integration hell: Ever tried integrating with a service that "has an API" but won't share specs? Now you don't need their permission
• Security research & bug bounty hunting: Reversing private APIs is essential for finding vulnerabilities — this tool accelerates that process dramatically

The tool is distributed via PyPI, available in the Arch Linux official repositories, and supports Docker^{↗ Bright Coding Blog} deployment — meaning you can spin it up anywhere, from your laptop to your CI/CD pipeline.

Key Features That Make It Irresistible

Let's break down what makes mitmproxy2swagger not just another API tool, but a genuine paradigm shift:

Dual Input Format Support

The tool doesn't lock you into a single capture workflow. Prefer mitmproxy's powerful filtering and scripting? Use .mitm flow files. Already have browser DevTools open? Export a HAR file and feed it directly. This flexibility means mitmproxy2swagger fits into your existing workflow, not the other way around.

Incremental, Non-Destructive Schema Building

Here's where it gets clever. mitmproxy2swagger uses a two-pass architecture with intelligent merging. Run it once to discover endpoints, curate which ones matter, then run again to generate full specifications. Existing schemas are preserved and extended — never overwritten. This means you can:

• Capture traffic from multiple sessions and merge them seamlessly
• Build up documentation over time as you discover new endpoints
• Collaborate with teammates who add their own captures to a shared schema

Smart Path Parameter Detection

The tool automatically identifies URL patterns and suggests path parameters. When it sees /users/104754/profile and /users/2/profile, it recognizes the numeric segment as a dynamic parameter and proposes {id} placeholders. You simply remove the ignore: prefix to confirm — no regex wrangling required.

Optional Example & Header Extraction

Pass --examples to embed real request/response payloads directly in your spec — invaluable for SDK generation and testing. Pass --headers to document authentication patterns, rate limiting headers, and content negotiation. Warning: These flags can capture sensitive data, so use them judiciously in production environments.

Docker-First Deployment

The included Dockerfile means you can run mitmproxy2swagger in isolated environments, CI pipelines, or shared infrastructure without polluting your Python environment. Volume-mount your capture files and schemas, and you're operational in seconds.

Real-World Use Cases Where It Absolutely Shines

1. The Legacy API Archaeology Expedition

Your company just acquired a startup. Their "well-documented API" turns out to be a single README last updated in 2019. With mitmproxy2swagger, you point their mobile app at your mitmproxy instance, exercise every feature, and generate a complete, accurate spec in under an hour. The acquisition integration that was projected for two weeks? Done in two days.

2. The Stubborn Third-Party Integration

That payment processor swears they have a "REST API" but their "documentation" is a PDF from 2017 and their support team ghosts you. No problem. Make a few test transactions through their web dashboard while capturing with browser DevTools, export the HAR, and mitmproxy2swagger reveals every endpoint, parameter, and response structure they didn't want to share.

3. The Microservice Documentation Debt

Your engineering team has been "moving fast and breaking things" for three years. Now you have 47 microservices and exactly zero current API specs. Deploy mitmproxy2swagger in your staging environment, run your integration test suite, and watch as actual traffic generates living documentation that reflects reality, not someone's outdated mental model.

4. The Security Research Goldmine

Bug bounty hunters and pentesters live and die by their ability to map attack surfaces. Private APIs, hidden admin endpoints, undocumented features — these are where the critical vulnerabilities hide. By capturing legitimate app traffic and running it through mitmproxy2swagger, researchers systematically reconstruct the complete API surface and identify targets for deeper analysis.

Step-by-Step Installation & Setup Guide

Getting started with mitmproxy2swagger is deliberately simple. Here's the complete setup:

Prerequisites

You'll need Python 3 and pip installed. Most modern systems satisfy this, but verify with:

python3 --version  # Should be 3.7+
pip3 --version

Installation Options

Choose your preferred method:

# Option 1: Standard pip installation (recommended)
pip install mitmproxy2swagger

# Option 2: Explicit pip3 for systems with both Python 2 and 3
pip3 install mitmproxy2swagger

# Option 3: Clone and build from source
git clone git@github.com:alufers/mitmproxy2swagger.git
cd mitmproxy2swagger
docker build -t mitmproxy2swagger .

Arch Linux users can install directly from official repositories:

pacman -S mitmproxy2swagger

mitmproxy Setup (for traffic capture)

If you haven't used mitmproxy before, install it separately:

pip install mitmproxy

Launch the web interface for easiest operation:

mitmweb
# Output: Web server listening at http://127.0.0.1:8081/
#         Proxy server listening at http://*:9999

Configure your client (browser, mobile app, or script) to use http://localhost:9999 as its HTTP proxy. For HTTPS traffic, you'll need to install mitmproxy's CA certificate — consult the official mitmproxy docs for platform-specific instructions.

Docker Workflow

For containerized environments, volume-mount your working directory:

docker run -it -v $PWD:/app mitmproxy2swagger mitmproxy2swagger [arguments]

This keeps your capture files and generated schemas persistent on the host while running the tool in isolation.

REAL Code Examples from the Repository

Let's walk through the actual workflow using exact commands and outputs from the official repository:

Example 1: Capturing Traffic with mitmweb

First, start the proxy and capture some traffic:

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

The web interface at http://127.0.0.1:8081/ lets you inspect flows in real-time. After exercising your target API, save the flows via File → Save in the UI. This produces a .mitm flow file — the raw material for schema generation.

Example 2: First Pass — Discovery Mode

Now run mitmproxy2swagger to discover endpoints. Here's the exact command structure:

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

For a concrete example, if you captured traffic from https://api.example.com/v1:

$ mitmproxy2swagger -i ./captured_flows.mitm -o ./api_schema.yaml -p https://api.example.com/v1

Or using Docker with volume mounting:

$ docker run -it -v $PWD:/app mitmproxy2swagger \
    mitmproxy2swagger -i /app/captured_flows.mitm \
                      -o /app/api_schema.yaml \
                      -p https://api.example.com/v1

This creates (or updates) api_schema.yaml with a special section for path review:

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

Critical insight: The ignore: prefix is a safety mechanism. It prevents accidental exposure of sensitive endpoints and lets you curate exactly what belongs in your public API specification. The greedy matching (top-down precedence) means you can define broad patterns early and specific exceptions later.

Example 3: Curating Your Schema

Edit api_schema.yaml with any text editor. Remove ignore: from paths you want documented:

x-path-templates:
  - /addresses                    # Now will be documented
  - /basket                       # Documented
  - /basket/add                   # Documented
  - ignore:/basket/checkouts      # Still hidden — maybe internal?
  - /basket/coupons/attach/{id}   # Parameterized and documented
  - ignore:/basket/coupons/attach/104754  # Specific instance ignored

Notice how the tool automatically suggested {id} for the coupon attachment path — no manual pattern recognition needed.

Example 4: Second Pass — Full Generation

Run the same command again to generate complete endpoint specifications:

$ mitmproxy2swagger -i ./captured_flows.mitm -o ./api_schema.yaml -p https://api.example.com/v1 --examples

The --examples flag embeds actual request/response bodies from your capture. Security warning: This may include authentication tokens, PII, or other sensitive data. Sanitize before sharing.

Similarly, --headers captures header patterns:

$ mitmproxy2swagger -i ./captured_flows.mitm -o ./api_schema.yaml -p https://api.example.com/v1 --headers

Important behavior: Existing endpoint descriptions are never overwritten on subsequent runs. This protects your manual edits and annotations. To force regeneration, delete the specific endpoint from the schema first.

Example 5: HAR File Processing (Browser DevTools)

For browser-captured traffic, the workflow is even simpler. In Chrome/Firefox DevTools:

1. Open Network tab
2. Perform API operations
3. Click Export HAR button
4. Save the .har file

Then process identically — mitmproxy2swagger auto-detects HAR format:

$ mitmproxy2swagger -i ./network_activity.har -o ./browser_api.yaml -p https://api.target.com

No format flags needed. The tool examines the file structure and routes to the appropriate parser automatically.

Advanced Usage & Best Practices

Multi-Session Schema Accumulation

Run captures from different environments (staging, production, various user roles) and repeatedly feed them to the same schema file. The merge logic is idempotent and conflict-aware — identical endpoints deepen their example pools, while new endpoints extend coverage.

CI/CD Integration

Embed in your pipeline for living documentation:

# GitHub Actions example snippet
- name: Generate API spec from integration tests
  run: |
    mitmproxy2swagger -i ./test_capture.mitm -o ./openapi.yaml -p ${{ env.API_BASE }}
- name: Validate generated spec
  run: |
    swagger-cli validate ./openapi.yaml

Parameter Refinement Strategy

The initial {id} suggestions are heuristic guesses. For production specs, review and constrain:

parameters:
  - name: id
    in: path
    required: true
    schema:
      type: integer
      minimum: 1  # Add constraints observed in traffic

Sensitive Data Sanitization Pipeline

When using --examples or --headers, implement a post-processing filter:

mitmproxy2swagger -i capture.mitm -o raw.yaml -p https://api.com --examples
python sanitize_schema.py raw.yaml clean.yaml  # Strip tokens, PII

Comparison with Alternatives

The verdict: Commercial tools lock you into ecosystems and pricing tiers. Manual documentation is a recipe for staleness. mitmproxy2swagger offers professional-grade output with zero lock-in, running entirely on your infrastructure.

FAQ

Does mitmproxy2swagger support OpenAPI 2.0 / Swagger 2.0?

No — it outputs OpenAPI 3.0 exclusively. Most modern tools (Swagger UI, ReDoc, code generators) handle 3.0 natively. If you absolutely need 2.0, use api-spec-converter as a post-processing step.

Can I use this with gRPC or GraphQL?

No. mitmproxy2swagger is purpose-built for REST/HTTP APIs. gRPC uses HTTP/2 framing with Protocol Buffers, and GraphQL typically exposes a single /graphql endpoint — neither matches the path-based REST assumption. For gRPC, look into grpcurl reflection. For GraphQL, use introspection queries.

How accurate are the generated schemas?

Structurally excellent, semantically incomplete. The tool infers types from observed JSON values, detects required fields by presence frequency, and maps status codes accurately. However, it cannot determine:

• Business logic constraints (e.g., "email must be corporate domain")
• Semantic validations (e.g., regex patterns for phone numbers)
• Authorization scopes per endpoint

Treat output as a 95% complete draft requiring human review for edge cases and business rules.

Is captured traffic secure?

You control everything. Unlike cloud-based tools, all processing happens locally. The --examples and --headers flags are opt-in and clearly warned. For maximum security, run in an isolated environment and sanitize outputs before sharing.

What if my API uses non-JSON payloads?

Currently, JSON is the primary supported content type for schema inference. Form data, XML, and binary payloads will show in captures but receive limited structural analysis. The project welcomes contributions for additional format support.

Can I contribute or request features?

Absolutely! The project uses Poetry for dependency management, pre-commit for code quality, and pytest for testing. See the Development section in the README for setup:

poetry install          # Install dependencies
pre-commit install      # Set up git hooks
poetry run pytest       # Run test suite

Does it work on Windows?

Yes, via Python/pip or Docker. Native Windows support for mitmproxy itself has improved significantly. For the smoothest experience, WSL2 + Docker is recommended.

Conclusion

The era of manual API archaeology is ending. mitmproxy2swagger represents a fundamental shift in how we approach API documentation — from speculative reconstruction based on incomplete information to empirical generation from actual observed behavior. It's not just faster; it's more accurate, because it documents what APIs actually do, not what someone claims they do.

Whether you're integrating with opaque third-party services, modernizing legacy systems, building security tools, or simply tired of maintaining docs that drift out of sync with code, this tool deserves immediate evaluation. The MIT license means no vendor lock-in. The Docker support means instant deployment anywhere. The two-pass workflow means human judgment stays in control while machines handle the tedious transcription.

I've seen tools promise automation before. Most deliver brittle, half-working solutions that require more cleanup than manual work would have. mitmproxy2swagger is different — it's battle-tested, thoughtfully designed, and genuinely production-ready.

Your next step: Head to github.com/alufers/mitmproxy2swagger, install with pip install mitmproxy2swagger, and run your first capture today. That API you've been dreading to document? It'll be spec-complete before your coffee gets cold.

Found this breakdown valuable? Star the repository, share with your team, and never write openapi.yaml from scratch again.