Apidog es una plataforma de colaboración y gestión de API que admite la importación de especificaciones de API en muchos formatos. Puede importar directamente casi todos los formatos de especificaciones de API principales, incluidos OpenAPI/Swagger, Postman Collections, archivos HAR y comandos cURL.
Sin embargo, en muchos proyectos reales, el principal desafío no es cómo importar especificaciones de API, sino que no hay especificaciones de API disponibles para importar en primer lugar. Algunos sistemas más antiguos o heredados nunca mantuvieron documentación de API y no tienen archivos OpenAPI o Swagger.
En estos casos, si necesita reconstruir rápidamente la documentación de API faltante o crear casos de prueba para que los testers puedan trabajar con datos reales, usar una herramienta de captura de paquetes suele ser el enfoque más rápido.
Al capturar el tráfico HTTP/HTTPS de la aplicación, filtrar las solicitudes útiles, exportarlas como HAR o cURL, y luego importarlas a Apidog, puede generar rápidamente documentación de API y sentar las bases para futuras pruebas de API.
Existen muchas herramientas disponibles para la grabación de tráfico. Este artículo utiliza Charles Proxy como ejemplo para demostrar las operaciones específicas involucradas, pero también puede usar alternativas como Proxyman, Fiddler o las herramientas de desarrollador integradas en su navegador para la captura de paquetes. El flujo de trabajo principal es esencialmente el mismo en todas estas herramientas.
Instalación y Configuración Básica de Charles
Charles ofrece una prueba gratuita de 30 días. Puede descargar la última versión desde el sitio web oficial e instalarla en su sistema.
Cuando inicie Charles por primera vez, es posible que le pregunte si desea configurar automáticamente la configuración de red. Se recomienda seleccionar "Grant Privileges" (Otorgar privilegios) para conceder los permisos necesarios. Esto permite a Charles capturar automáticamente el tráfico HTTP de su sistema.
Instalación del Certificado Raíz de Charles para Captura HTTPS
Para capturar tráfico HTTPS, necesita instalar el certificado raíz de Charles. Este paso es esencial porque la mayoría de las API modernas utilizan HTTPS.
En macOS:
- Haga clic en "Help (Ayuda) → SSL Proxying (Proxy SSL) → Install Charles Root Certificate (Instalar certificado raíz de Charles)" en la barra de menú
- La aplicación Acceso a Llaveros (Keychain Access) se abrirá automáticamente
- Busque y localice el certificado de Charles Proxy
- Haga doble clic en él y cambie la configuración de confianza a "Always Trust" (Confiar siempre)
En Windows:
- Haga clic en "Help (Ayuda) → SSL Proxying (Proxy SSL) → Install Charles Root Certificate (Instalar certificado raíz de Charles)" en la barra de menú
- Durante el proceso de instalación, instale el certificado en el almacén de "Trusted Root Certification Authorities" (Autoridades de certificación raíz de confianza)
Habilitar el Proxy SSL
Después de instalar el certificado, debe habilitar el proxy SSL:
- Seleccione Proxy → SSL Proxying Settings (Configuración del Proxy SSL) en la barra de menú de Charles
- Marque la opción "Enable SSL Proxying" (Habilitar proxy SSL)
3. Añada a la lista los nombres de dominio (Host) y puertos (Puerto 443) que desee capturar
4. También puede usar * para monitorizar todos los dominios
Una vez completada la configuración, Charles puede capturar solicitudes y respuestas HTTP/HTTPS completas.
Consejo: Si no está seguro de qué dominios utiliza su aplicación, puede operar primero la aplicación libremente y luego observar las solicitudes en "Encrypted" (Cifrado) en la lista de sesiones de Charles. Anote los dominios correspondientes y luego añádalos a la configuración de Proxy SSL de Charles.
Grabación del Tráfico de API de su Aplicación
Inicie la aplicación o página web que desea analizar e interactúe con diversas funciones, como iniciar sesión, consultar datos, enviar formularios o subir archivos. El árbol de sesiones en el lado izquierdo de Charles se actualizará en tiempo real, agrupando las solicitudes por dominio y URL.
Cuando selecciona una solicitud específica, el panel derecho muestra la información básica y el contenido de la respuesta de esa solicitud. En la pestaña Contenidos, JSON y otras respuestas se colapsan en una estructura de árbol, lo que facilita la comprensión rápida de la estructura y los campos de los datos.
Filtrado y Exportación de Endpoints de API
Una vez completada la grabación, es posible que encuentre que se ha capturado una gran cantidad de solicitudes. Además de las llamadas a la API reales, hay varias solicitudes de recursos estáticos, llamadas a servicios de terceros y otro tráfico de red. En este punto, debe filtrar y conservar solo los endpoints que le interesan.
Opciones de Filtrado
1. Enfocarse en dominios o rutas específicas:
Haga clic derecho en un dominio o ruta y seleccione "Focus" (Enfocar)
Charles conservará solo las solicitudes bajo ese nodo, lo que facilita su análisis
2. Eliminar solicitudes no relacionadas:
Haga clic derecho en solicitudes no relacionadas y seleccione "Clear" (Borrar) para eliminarlas
O seleccione múltiples solicitudes y elimínelas en masa
3. Manejar problemas de caché:
Si el caché hace que HTML o JSON no se muestren correctamente, haga clic derecho y seleccione "No Caching" (Sin caché)
Esto hace que Charles ignore el caché en solicitudes posteriores, permitiéndole capturar el contenido completo de la respuesta
Exportar como archivo HAR
Una vez finalizado el filtrado, exporte sus sesiones seleccionadas:
- Seleccione las sesiones que desea exportar:
Puede seleccionar un nodo de dominio completo, o
Mantenga pulsado Cmd (Mac) o Ctrl (Windows) y seleccione solicitudes específicas individualmente
Seleccione File (Archivo) → Export Session (Exportar sesión) en la barra de menú
En el cuadro de diálogo de exportación, elija exportar en formato "HTTP Archive (.har)" para crear un archivo HAR
Importación a Apidog para Generar Automáticamente Documentación de API
Ahora es el momento de importar su tráfico capturado a Apidog:
- Abra el cliente de Apidog
2. Vaya a Project Settings (Configuración del proyecto) → Import Data (Importar datos) → .har File (Archivo .har)
3. Seleccione el archivo HAR que exportó desde Charles
Apidog analizará automáticamente el contenido del archivo y mostrará la información del endpoint detectado en el área de vista previa, incluyendo:
- El número de endpoints detectados
- Métodos de solicitud (GET, POST, PUT, DELETE, etc.)
Durante el proceso de importación, puede configurar opciones como:
- En qué módulo importar
- Si desea sobrescribir los endpoints existentes
Una vez completada la importación, puede ver los endpoints en el módulo correspondiente.
Refinamiento y Optimización de la Documentación de API
La documentación de API generada automáticamente es un excelente punto de partida, pero generalmente requiere ajustes adicionales para cumplir con sus requisitos comerciales. Aquí hay algunas mejoras comunes:
- Mejorar nombres de endpoints: Cambie nombres genéricos por otros más descriptivos
- Añadir descripciones de parámetros: Documente lo que hace cada parámetro y cuándo usarlo
- Refinar componentes de respuesta: Organice los componentes de respuesta para que coincidan con su lógica de negocio
- Añadir ejemplos: Incluya ejemplos de solicitudes y respuestas
- Configuración de autenticación: Si un endpoint requiere autenticación, configure la información correspondiente en las variables de entorno de Apidog o en la configuración de autenticación. Esto asegura que sus llamadas a la API funcionen correctamente durante las pruebas.
Conclusión Final
Al grabar el tráfico HTTP/HTTPS utilizando herramientas de captura de paquetes y luego importarlo a Apidog, puede generar rápidamente documentación de API y proporcionar soporte de datos reales para las pruebas.
Ya sea un navegador, un cliente de escritorio o una aplicación móvil, este método puede reducir significativamente el tiempo dedicado a preparar la documentación de la API y permitir que su equipo comience rápidamente con las pruebas y el desarrollo de la API.