OpenAPI2Insomnia: convierte tu especificación OpenAPI en una colección de Insomnia lista para probar

Probar una API en Insomnia suele empezar con la misma rutina manual: importar la especificación, revisar operación por operación, crear peticiones, rellenar parámetros de ejemplo, configurar la autenticación y —si el equipo es riguroso— escribir scripts que validen que cada respuesta devuelve el código correcto y un cuerpo conforme al esquema. Multiplica ese esfuerzo por decenas de endpoints y por los distintos códigos de respuesta de cada uno, y la preparación de las pruebas se convierte en un proyecto en sí mismo.

OpenAPI2Insomnia, la herramienta open source de la comunidad APIAddicts, automatiza todo ese trabajo. Es una CLI ligera escrita en Node.js que convierte una especificación OpenAPI 3.0.x en una colección de Insomnia v5 lista para importar y ejecutar. Y no se limita a crear peticiones: genera casos de prueba con validaciones automáticas para los escenarios de éxito y de error de cada operación.

Qué hace OpenAPI2Insomnia

El principio de partida es el mismo que guía el enfoque API-first: el contrato de la API contiene toda la información necesaria para probarla. OpenAPI2Insomnia aprovecha ese contrato para generar, por cada operación, un conjunto de casos de prueba (TC) que cubren tanto el camino feliz como los errores más habituales: un TC base de éxito por operación, variantes por parámetro para ejercitar las distintas combinaciones de entrada, y TC de error para los códigos 400, 401, 403 y 404.

Lo verdaderamente diferencial es que cada caso de prueba incluye un script de validación afterResponse que comprueba automáticamente el código de estado devuelto y valida el cuerpo de la respuesta contra el esquema definido en la especificación. Es decir, la colección no solo lanza peticiones: verifica que la API se comporta según su contrato, sin que tengas que escribir una sola aserción a mano.

Instalación y primer uso

OpenAPI2Insomnia requiere Node.js 20 o superior. Su instalación es la propia de cualquier paquete global de npm:

npm install -g openapi2insomnia

A partir de ahí, convertir una especificación es tan simple como una línea de comandos. El comando principal es o2i convert, que acepta como entrada tanto un archivo local como una URL HTTPS:

# Salida por pantalla (stdout)
o2i convert -i openapi.yaml
# Salida a un archivo
o2i convert -i openapi.yaml -o collection.yaml
# Con archivo de configuración (un fichero por entorno)
o2i convert -i openapi.yaml -c o2i.config.json
# Desde una URL remota
o2i convert -i https://api.example.com/openapi.yaml -o collection.yaml

Las opciones son mínimas y claras: -i / --input (obligatoria) para indicar la especificación, -o / --output para el archivo de salida —si se omite, escribe por stdout— y -c / --config para apuntar a un fichero de configuración. Para desarrollo, el proyecto usa pnpm 9 o superior y se compila con pnpm build.

La potencia está en la configuración por entornos

Sin archivo de configuración, la herramienta genera una única colección usando como base_url la URL del servidor declarada en la especificación. Pero su verdadero potencial aparece con el fichero o2i.config.json, que permite generar una colección por entorno —DEV, PRE, PRO…— cada una con su propia URL, sus credenciales OAuth2 y sus opciones de generación.

Entre las opciones más útiles encontramos: minimal_endpoints, que genera solo el TC base de éxito por operación para colecciones más ligeras; generate_oneOf_anyOf, que crea un conjunto de TC por cada variante de esquema cuando un cuerpo usa oneOf/anyOf; los bloques examples.correct y examples.wrong, que definen los valores válidos de los TC de éxito y los inválidos que se usan a propósito en los TC de 400; host_server_pattern, un patrón tipo SQL-LIKE que selecciona automáticamente la URL correcta de la lista de servers[]; microcks_headers, para integrarse con Microcks; read_only, que limita los casos a operaciones GET; y has_scopes, application_token y number_of_scopes, que clonan los TC de éxito para cada tipo de token y cubren distintos escenarios de autorización.

Esta granularidad convierte a OpenAPI2Insomnia en algo más que un simple conversor: es una herramienta que se adapta a la realidad de proyectos con varios entornos, autenticación OAuth2 y matices de autorización por scopes.

Por qué merece la pena incorporarla a tu flujo

Un ejemplo de flujo de trabajo

Imagina un equipo que mantiene una API con entornos de desarrollo y preproducción, protegida con OAuth2 mediante Keycloak. Con OpenAPI2Insomnia definen un o2i.config.json con dos entornos, cada uno con su base_url, su token_url y su client_id. Al ejecutar o2i convert -i openapi.yaml -c o2i.config.json obtienen dos colecciones de Insomnia —una por entorno— que un tester importa y ejecuta directamente. Cada operación llega con su caso de éxito, sus variantes y sus casos de error ya validados contra el esquema.

Open source y comunidad

OpenAPI2Insomnia se distribuye bajo licencia GNU Lesser General Public License v3.0 y forma parte del ecosistema de herramientas abiertas de APIAddicts. Como todo proyecto de la comunidad, mejora con la participación de quienes lo utilizan: puedes clonarlo, proponer mejoras, reportar issues y contribuir con código a través de GitHub.

Conclusión

OpenAPI2Insomnia lleva la idea API-first hasta su conclusión lógica en el mundo del testing: si el contrato ya describe la API por completo, ¿por qué escribir las pruebas a mano? Con una sola línea de comandos transformas tu especificación OpenAPI 3.0.x en una colección de Insomnia rica, con casos de éxito y de error y validación automática contra el esquema, adaptada a tantos entornos como necesites.

Pruébalo con tu propia API y comparte tu experiencia con la comunidad. En APIAddicts seguimos construyendo herramientas abiertas que hacen que trabajar con APIs sea más rápido, más fiable y más disfrutable.