mitmproxy2swagger

mitmproxy2swagger es una herramienta de línea de comandos que transforma capturas de tráfico HTTP (provenientes de archivos de flujo de mitmproxy o exportaciones HAR de las herramientas de desarrollo del navegador) en especificaciones OpenAPI 3.0 (Swagger). Esto permite a los desarrolladores realizar rápidamente ingeniería inversa de APIs REST con solo ejecutar una aplicación y registrar sus solicitudes de red, en lugar de examinar manualmente endpoints y parámetros. ## Capacidades principales - **Formatos de entrada**: Acepta archivos de flujo de mitmproxy (`.mitm` mediante mitmweb/mitmproxy) y archivos HAR (detección automática). - **Flujo de trabajo en dos pasadas**: La primera pasada genera una plantilla con todas las rutas descubiertas; los usuarios editan la plantilla para seleccionar qué endpoints incluir y ajustar los parámetros de ruta (por ejemplo, reemplazar IDs dinámicos con marcadores de posición `{id}`). La segunda pasada completa los esquemas detallados de solicitudes/respuestas, combinando datos de múltiples sesiones de captura sin sobrescribir contenido existente. - **Esquemas extensibles**: Puede fusionar datos nuevos en un archivo de esquema existente, lo que permite mejoras incrementales entre capturas. - **Enriquecimiento opcional de datos**: Las opciones `--examples` y `--headers` incluyen ejemplos de cargas útiles e información de cabeceras (con una advertencia sobre posibles datos sensibles). - **Formato de salida**: Genera archivos YAML compatibles con OpenAPI 3.0, utilizables con herramientas de documentación como Redoc. ## Uso típico 1. Capture tráfico HTTP (por ejemplo, con `mitmweb` y luego guarde el archivo de flujo). 2. Ejecute `mitmproxy2swagger -i flow.mitm -o schema.yaml -p https://api.example.com/v1` para crear la plantilla inicial. 3. Edite schema.yaml: elimine los prefijos `ignore:` de las rutas deseadas. 4. Vuelva a ejecutar el comando para generar las definiciones completas de endpoints. ## Detalles técnicos - Escrito en Python, instalable mediante pip o ejecutable con Docker. - Disponible en PyPI y en los repositorios de Arch Linux. - El desarrollo utiliza uv, prek (linting) y pytest para pruebas; las contribuciones son bienvenidas. - Licencia MIT. ## Caso de uso de ejemplo Dada una aplicación que realiza solicitudes a `https://api.example.com/v1/login`, `/users/2` y `/users/2/profile`, la herramienta sugeriría `https://api.example.com/v1` como prefijo y luego guiaría al usuario para definir plantillas de ruta como `/users/{id}` y `/users/{id}/profile`. Para una demostración práctica, consulte el directorio `example_outputs/` incluido, con un esquema generado y un ejemplo de documentación HTML renderizada.