https://github.com/alufers/mitmproxy2swagger Skip to content Navigation Menu Toggle navigation Sign in * Product + GitHub Copilot Write better code with AI + Security Find and fix vulnerabilities + Actions Automate any workflow + Codespaces Instant dev environments + Issues Plan and track work + Code Review Manage code changes + Discussions Collaborate outside of code + Code Search Find more, search less Explore + All features + Documentation + GitHub Skills + Blog * Solutions By company size + Enterprises + Small and medium teams + Startups By use case + DevSecOps + DevOps + CI/CD + View all use cases By industry + Healthcare + Financial services + Manufacturing + Government + View all industries View all solutions * Resources Topics + AI + DevOps + Security + Software Development + View all Explore + Learning Pathways + White papers, Ebooks, Webinars + Customer Stories + Partners + Executive Insights * Open Source + GitHub Sponsors Fund open source developers + The ReadME Project GitHub community articles Repositories + Topics + Trending + Collections * Enterprise + Enterprise platform AI-powered developer platform Available add-ons + Advanced Security Enterprise-grade security features + GitHub Copilot Enterprise-grade AI features + Premium Support Enterprise-grade 24/7 support * Pricing Search or jump to... Search code, repositories, users, issues, pull requests... Search [ ] Clear Search syntax tips Provide feedback We read every piece of feedback, and take your input very seriously. [ ] [ ] Include my email address so I can be contacted Cancel Submit feedback Saved searches Use saved searches to filter your results more quickly Name [ ] Query [ ] To see all available qualifiers, see our documentation. Cancel Create saved search Sign in Sign up Reseting focus You signed in with another tab or window. Reload to refresh your session. You signed out in another tab or window. Reload to refresh your session. You switched accounts on another tab or window. Reload to refresh your session. Dismiss alert {{ message }} alufers / mitmproxy2swagger Public * Notifications You must be signed in to change notification settings * Fork 273 * Star 7.4k Automagically reverse-engineer REST APIs via capturing traffic 7.4k stars 273 forks Branches Tags Activity Star Notifications You must be signed in to change notification settings * Code * Issues 12 * Pull requests 6 * Actions * Projects 0 * Security * Insights Additional navigation options * Code * Issues * Pull requests * Actions * Projects * Security * Insights alufers/mitmproxy2swagger master BranchesTags [ ] Go to file Code Folders and files Last commit Last Name Name message commit date Latest commit History 314 Commits .github .github docs docs example_outputs example_outputs mitmproxy2swagger mitmproxy2swagger testdata testdata .dockerignore .dockerignore .flake8 .flake8 .gitignore .gitignore .markdownlint.yaml .markdownlint.yaml .mypy.ini .mypy.ini .pre-commit-config.yaml .pre-commit-config.yaml .yamllint .yamllint Dockerfile Dockerfile README.md README.md poetry.lock poetry.lock pyproject.toml pyproject.toml specs.yml specs.yml View all files Repository files navigation * README mitmproxy2swagger PyPI version Arch Linux repository video.mp4 A tool for automatically converting mitmproxy captures to OpenAPI 3.0 specifications. This means that you can automatically reverse-engineer REST APIs by just running the apps and capturing the traffic. --------------------------------------------------------------------- NEW! Added support for processing HAR exported from the browser DevTools. See Usage - HAR for more details. --------------------------------------------------------------------- Installation First you will need python3 and pip3. $ pip install mitmproxy2swagger # ... or ... $ pip3 install mitmproxy2swagger # ... or ... $ git clone git@github.com:alufers/mitmproxy2swagger.git $ cd mitmproxy2swagger $ docker build -t mitmproxy2swagger . Then clone the repo and run mitmproxy2swagger as per examples below. Usage Mitmproxy To create a specification by inspecting HTTP traffic you will need to: 1. Capture the traffic by using the mitmproxy tool. I personally recommend using mitmweb, which is a web interface built-in to mitmproxy. $ mitmweb Web server listening at http://127.0.0.1:8081/ Proxy server listening at http://*:9999 ... IMPORTANT To configure your client to use the proxy exposed by mitm proxy, please consult the mitmproxy documentation for more information. 2. Save the traffic to a flow file. In mitmweb you can do this by using the "File" menu and selecting "Save": A screenshot showing the location of the "Save" option in the "File" menu 3. Run the first pass of mitmproxy2swagger: $ mitmproxy2swagger -i -o -p # ... or ... $ docker run -it -v $PWD:/app mitmproxy2swagger mitmproxy2swagger -i -o -p Please note that you can use an existing schema, in which case the existing schema will be extended with the new data. You can also run it a few times with different flow captures, the captured data will be safely merged. is the base url of the API you wish to reverse-engineer. You will need to obtain it by observing the requests being made in mitmproxy. For example if an app has made requests like these: https://api.example.com/v1/login https://api.example.com/v1/users/2 https://api.example.com/v1/users/2/profile The likely prefix is https://api.example.com/v1. 4. Running the first pass should have created a section in the schema file like this: 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 You should edit the schema file with a text editor and remove the ignore: prefix from the paths you wish to be generated. You can also adjust the parameters appearing in the paths. 5. Run the second pass of mitmproxy2swagger: $ mitmproxy2swagger -i -o -p [--examples] # ... or ... $ docker run -it -v $PWD:/app mitmproxy2swagger mitmproxy2swagger -i -o -p [--examples] Run the command a second time (with the same schema file). It will pick up the edited lines and generate endpoint descriptions. Please note that mitmproxy2swagger will not overwrite existing endpoint descriptions, if you want to overwrite them, you can delete them before running the second pass. Passing --examples will add example data to requests and responses. Take caution when using this option, as it may add sensitive data (tokens, passwords, personal information etc.) to the schema. Passing --headers will add headers data to requests and responses. Take caution when using this option, as it may add sensitive data (tokens, passwords, personal information etc.) to the schema. HAR 1. Capture and export the traffic from the browser DevTools. In the browser DevTools, go to the Network tab and click the "Export HAR" button. A screenshot showing where the export har button is located 2. Continue the same way you would do with the mitmproxy dump. mitmproxy2swagger will automatically detect the HAR file and process it. Example output See the examples. You will find a generated schema there and an html file with the generated documentation (via redoc-cli). See the generated html file here. Development and contributing This project uses: * poetry for dependency management * pre-commit for code formatting and linting * pytest for unit testing To install the dependencies: poetry install Run linters: pre-commit run --all-files Install pre-commit hooks: pre-commit install Run tests: poetry run pytest Run tests with coverage: poetry run pytest --cov=mitmproxy2swagger License MIT About Automagically reverse-engineer REST APIs via capturing traffic Topics reverse-engineering swagger openapi mitmproxy Resources Readme Activity Stars 7.4k stars Watchers 28 watching Forks 273 forks Report repository Releases 19 Mitmproxy 11 support Latest Dec 12, 2024 + 18 releases Packages 0 Contributors 18 * @alufers * @dependabot[bot] * @pre-commit-ci[bot] * @timvahlbrock * @victorlpgazolli * @kpcyrd * @Sh4rK * @gadcam * @K0RSHAK * @fabaff * @jwilk * @willtrnr * @scw007 * @tweska + 4 contributors Languages * HTML 96.7% * Python 3.2% * Dockerfile 0.1% Footer (c) 2025 GitHub, Inc. Footer navigation * Terms * Privacy * Security * Status * Docs * Contact * Manage cookies * Do not share my personal information You can't perform that action at this time.