Proxyman vs mitmproxy: generar OpenAPI desde tráfico capturado
Tienes una API, pero su documentación no existe o está desactualizada. Puedes ver las solicitudes en tu app, pero escribir a mano cada ruta, parámetro y respuesta llevaría horas.
Una herramienta de depuración HTTP puede ayudarte. Puede capturar las solicitudes reales que envía tu app. El siguiente paso es convertir esas solicitudes en un documento OpenAPI que las personas y las herramientas puedan entender.
Tanto mitmproxy como Proxyman pueden formar parte de este flujo de trabajo. La diferencia principal es cuántos pasos necesitas. Con mitmproxy, la solución habitual usa una herramienta de línea de comandos independiente. Con Proxyman, la exportación a OpenAPI viene integrada en la app.
En esta guía aprenderás:
- Qué es OpenAPI y por qué es útil
- Cómo funciona el flujo de trabajo actual con mitmproxy
- Dónde puede resultar difícil este flujo para quienes empiezan
- Cómo exportar OpenAPI en YAML o HTML con Proxyman
- Qué revisar antes de compartir el documento generado
¿Qué es OpenAPI?
OpenAPI es un formato estándar para describir una API REST. Indica a las personas y al software cosas como:
- Qué URL están disponibles
- Qué métodos HTTP utilizan, como
GET,POSToDELETE - Qué parámetros de consulta o de ruta aceptan
- Cómo es el cuerpo de la solicitud
- Qué puede devolver el servidor
- Qué códigos de estado se usan
Por ejemplo, tu app puede enviar esta solicitud:
GET https://api.example.com/users/123
Un documento OpenAPI puede describir esa solicitud como una ruta del tipo /users/{id}. También puede describir el JSON que devuelve el servidor.
Los archivos OpenAPI suelen escribirse en YAML o JSON. Puedes abrirlos con herramientas como Swagger Editor, usarlos para crear documentación de API o generar código cliente a partir de ellos.
¿Por qué generar OpenAPI a partir de tráfico real?
La mejor documentación de una API se escribe y mantiene junto con el código fuente de la API. Sin embargo, en proyectos reales esa documentación puede estar incompleta, desactualizada o no estar disponible.
Generar un primer borrador a partir del tráfico capturado es útil cuando:
- Trabajas con una API heredada
- Te incorporas a un proyecto con poca documentación
- Necesitas entender una API que usa tu propia app móvil o web
- Quieres darle a QA una lista de endpoints reales
- Quieres comparar la API actual con un documento anterior
- Necesitas un punto de partida rápido antes de escribir una documentación mejor
El tráfico capturado te ofrece ejemplos reales. Muestra lo que envió la app y lo que devolvió el servidor durante esa sesión.
Captura solo APIs, apps y cuentas que tengas permiso para inspeccionar. Una solicitud capturada puede contener contraseñas, cookies, tokens de acceso, datos personales o información privada de la empresa.
La solución actual con mitmproxy
mitmproxy es un proxy interceptor gratuito y muy potente. Puede capturar tráfico HTTP, HTTPS y WebSocket. Es una buena opción para desarrolladores a quienes les gustan las herramientas de terminal, Python y los flujos de trabajo automatizados.
mitmproxy no ofrece la exportación a OpenAPI como una acción integrada y sencilla en su interfaz principal. Una solución habitual es usar el proyecto comunitario independiente mitmproxy2swagger.
El flujo de trabajo habitual es el siguiente:
- Instala e inicia mitmproxy o mitmweb.
- Configura tu app o dispositivo para enviar el tráfico a través del proxy.
- Captura las solicitudes de API que necesitas.
- Guarda el tráfico capturado como archivo de flujo de mitmproxy o como archivo HAR.
- Instala
mitmproxy2swaggery su entorno de Python necesario. - Ejecuta un comando con el archivo de entrada, el archivo de salida y el prefijo de URL de la API.
- Abre el primer resultado en YAML y elige qué rutas detectadas incluir.
- Ejecuta el comando de nuevo para crear el documento OpenAPI completo.
Un primer comando podría verse así:
mitmproxy2swagger \
-i capture.flow \
-o api-schema.yaml \
-p https://api.example.com/v1
La primera pasada encuentra posibles rutas de API. Después revisas el YAML, eliminas ignore: de las rutas que quieres y corriges los parámetros de ruta. Luego vuelves a ejecutar la herramienta. Las opciones adicionales pueden añadir ejemplos o encabezados.
Esta solución es flexible y encaja bien en un script o en un proceso de compilación repetible. Pero tiene varias piezas que gestionar.
¿Qué tiene de difícil la solución actual?
El problema no es que mitmproxy no pueda capturar el tráfico. Sí puede. La dificultad está en todo lo que hay entre la captura y el archivo OpenAPI final.
1. Necesitas más de una herramienta
Capturas el tráfico con mitmproxy y, después, instalas y ejecutas otro proyecto para crear OpenAPI. Cada herramienta tiene su propia configuración, comandos, versiones y formatos de archivo.
Para una persona con experiencia en la línea de comandos, esto puede estar bien. Para un desarrollador nuevo o un tester de QA, puede ralentizar una tarea que debería sentirse sencilla.
2. Necesitas un flujo de trabajo en dos pasos
El primer archivo generado no es el resultado final. Hay que abrirlo, elegir rutas, editar valores y volver a ejecutar el comando.
Esa revisión adicional es útil, pero puede resultar sorprendente si solo quieres un documento rápido a partir de unas pocas solicitudes seleccionadas.
3. Una captura completa puede tener mucho ruido
Un navegador o una app móvil puede llamar a servicios de analítica, servidores de imágenes, feature flags, servicios de autenticación y muchos otros hosts. Si exportas la sesión completa, tu resultado OpenAPI puede contener mucho más de lo que querías de la API.
Es más fácil cuando puedes ver las solicitudes y seleccionar solo las útiles antes de exportar.
4. Los ejemplos pueden contener datos privados
El tráfico real es útil porque contiene valores reales. Esos valores también pueden ser peligrosos. Un ejemplo puede incluir un token, una dirección de correo electrónico, una URL interna o un ID de usuario.
Revisa siempre el resultado antes de hacer commit en Git, subirlo a un sitio de documentación o compartirlo con otra persona.
La solución más sencilla con Proxyman
Proxyman incluye la exportación a OpenAPI en la app para macOS. Capturas el tráfico, seleccionas las solicitudes que quieres y las exportas como OpenAPI en YAML o HTML.
No hay ningún conversor adicional que instalar ni un segundo comando que ejecutar.
Paso 1: captura el tráfico de tu API
Descarga y abre la versión actual de Proxyman para macOS. Instala y confía en el certificado de Proxyman siguiendo la configuración que aparece dentro de la app.
Después usa tu sitio web, simulador o app móvil y realiza la acción que quieres documentar. Por ejemplo, abre una pantalla de perfil para capturar la solicitud que carga un usuario.
Asegúrate de que Proxyman pueda ver la solicitud y la respuesta descifradas.
Para obtener un resultado limpio, captura un solo recorrido de usuario pequeño cada vez. Puedes borrar la sesión actual antes de empezar.
Paso 2: selecciona las solicitudes útiles
Busca el host de la API en la tabla principal. Selecciona las solicitudes que deben formar parte de tu documento.
No necesitas seleccionar todas las solicitudes. Deja fuera imágenes, analítica y otros servicios que no forman parte de la API.
Si el mismo endpoint aparece muchas veces, empieza con una respuesta exitosa clara. Más adelante puedes añadir más ejemplos cuando muestren una solicitud o una estructura de respuesta distinta.
Paso 3: exporta OpenAPI
Haz clic derecho en las solicitudes seleccionadas y después elige:
Export → OpenAPI → OpenAPI YAML
Elige dónde guardar el archivo.
Eso es todo el flujo de exportación. Proxyman crea el archivo OpenAPI a partir de las solicitudes y respuestas que seleccionaste.
Paso 4: revisa el archivo YAML
Abre el YAML en Swagger Editor o en tu editor de código habitual. Comprueba que las rutas, los métodos, los parámetros y los esquemas tengan sentido.
El documento generado es un punto de partida. El tráfico real muestra lo que ocurrió en una sesión. No puede conocer todas las respuestas de error posibles ni todos los valores opcionales que admite el servidor.
Paso 5: exporta HTML legible cuando haga falta
Si un compañero solo necesita leer la API, exporta HTML en su lugar:
Export → OpenAPI → OpenAPI HTML
El HTML es útil para una revisión rápida o para una entrega privada. El YAML es mejor si piensas editar el documento, validarlo o usarlo con otras herramientas de OpenAPI.
Proxyman vs mitmproxy para OpenAPI
| Tarea | Flujo de trabajo con mitmproxy | Flujo de trabajo con Proxyman |
|---|---|---|
| Capturar tráfico HTTPS | Integrado | Integrado |
| Elegir solicitudes visualmente | Disponible en interfaces interactivas | Seleccionar filas en la tabla principal |
| Generar OpenAPI | Herramienta comunitaria independiente | Integrado en Proxyman |
| Configuración | Proxy más conversor de Python | App de Proxyman |
| Proceso | Capturar, guardar, ejecutar la primera pasada, editar, volver a ejecutar | Capturar, seleccionar, exportar |
| Resultado | OpenAPI YAML | OpenAPI YAML o HTML |
| Ideal para | Automatización y flujos de trabajo de línea de comandos | Trabajo visual rápido de desarrolladores y QA |
mitmproxy sigue siendo una herramienta muy sólida. Si ya automatizas la captura de tráfico con Python, su flujo de trabajo puede encajar bien en tu proyecto. Proxyman resulta útil cuando quieres inspeccionar una sesión y crear un documento útil sin montar antes un proceso de línea de comandos.
Revisa el documento generado antes de compartirlo
Independientemente de la herramienta que uses, revisa estos puntos:
- Elimina los datos sensibles. Busca tokens, cookies, contraseñas, encabezados privados, direcciones de correo electrónico y datos personales.
- Revisa los parámetros de ruta. Una ruta como
/users/123puede necesitar convertirse en/users/{id}. - Añade las respuestas que faltan. Tu captura puede incluir
200, pero no400,401,404ni500. - Revisa los campos obligatorios. Un solo ejemplo no puede demostrar que todos los campos sean obligatorios.
- Revisa los tipos de datos. Un valor que parece un número en una respuesta puede ser en realidad un ID de tipo cadena.
- Añade los detalles de autenticación. Describe la autenticación esperada sin copiar un secreto real.
- Usa nombres y descripciones claros. Los esquemas generados siguen necesitando explicaciones humanas.
- Valida el archivo. Ábrelo en un editor de OpenAPI y corrige las advertencias.
Conclusión
Generar OpenAPI a partir del tráfico puede ahorrar mucho tiempo, sobre todo cuando falta la documentación original. mitmproxy puede encargarse de esta tarea mediante un conversor independiente y un flujo de trabajo de línea de comandos. Ese enfoque es flexible, pero obliga al usuario a gestionar más pasos.
Proxyman reúne el flujo de trabajo básico en un solo lugar: captura las solicitudes, selecciona las filas útiles y exporta OpenAPI en YAML o HTML. Es un punto de partida cómodo para desarrolladores y equipos de QA que quieren un documento rápido y piensan revisarlo después.
Siguientes pasos
