mitmproxy2swagger

What is the project about?

mitmproxy2swagger is a tool that automatically converts network traffic captures from mitmproxy (or HAR files from browser DevTools) into OpenAPI 3.0 (Swagger) specifications. It's a reverse-engineering tool for REST APIs.

What problem does it solve?

It solves the problem of manually creating OpenAPI/Swagger documentation for existing APIs. Instead of writing the documentation by hand, which is time-consuming and error-prone, you can capture the actual API calls made by an application and automatically generate a specification. This is particularly useful when:

• Documenting an undocumented API.
• Understanding the structure of an API you don't control.
• Creating a starting point for API documentation that can then be refined.
• Reverse-engineering an API for testing or integration purposes.

What are the features of the project?

• Automatic Conversion: Transforms mitmproxy flow files or HAR files into OpenAPI 3.0 specifications.
• Iterative Process: Uses a two-pass approach. The first pass identifies potential endpoints and creates a basic schema. The second pass, after user review and editing of the x-path-templates section, generates the full endpoint descriptions.
• Schema Merging: Can extend existing OpenAPI schemas, allowing you to combine captures from multiple sessions or sources.
• API Prefix Handling: Allows specifying the base URL of the API to correctly structure the generated paths.
• Optional Example Data: Can include example request and response bodies in the generated schema (with a warning about potential sensitive data).
• Optional Header Data: Can include header data in the generated schema (with a warning about potential sensitive data).
• HAR Support: Directly processes HAR files exported from browser developer tools, in addition to mitmproxy captures.
• Docker Support: Provides instructions for running the tool within a Docker container.

What are the technologies used in the project?

• Python 3: The primary programming language.
• mitmproxy: A powerful interactive HTTPS proxy (used for capturing network traffic).
• OpenAPI 3.0 (Swagger): The specification format for describing REST APIs.
• Poetry: Python dependency management.
• pre-commit: For code formatting and linting (likely using tools like Black, isort, flake8, etc., though not explicitly listed).
• pytest: For unit testing.
• HAR (HTTP Archive): A JSON-formatted archive file format for logging of a web browser's interaction with a site.

What are the benefits of the project?

• Saves Time: Automates a significant portion of API documentation creation.
• Increases Accuracy: Generates documentation based on actual API usage, reducing the risk of errors compared to manual documentation.
• Facilitates Understanding: Provides a clear, structured view of an API's endpoints, parameters, and data formats.
• Improves Collaboration: Creates a standardized API specification that can be shared among developers, testers, and other stakeholders.
• Enables Tooling: The generated OpenAPI specification can be used with various tools for API testing, mocking, code generation, and documentation rendering (like Redoc, as shown in the example).

What are the use cases of the project?

• Reverse-engineering undocumented APIs: Discovering the structure and functionality of APIs without existing documentation.
• Documenting legacy systems: Creating API documentation for older applications that may lack it.
• API integration: Understanding how to interact with third-party APIs.
• Security auditing: Analyzing API traffic to identify potential vulnerabilities.
• Testing: Generating API specifications that can be used for automated testing.
• Creating mock servers: Using the generated specification to create mock servers for development and testing.
• Generating client SDKs: Using the OpenAPI specification to automatically generate client libraries in various programming languages.