openapi2insomnia: Convierte tu especificación OpenAPI en una colección Insomnia lista para usar

¿Qué es Insomnia?

Insomnia es un cliente REST y GraphQL de código abierto que permite a desarrolladores y equipos de API diseñar, probar y depurar APIs de forma sencilla e intuitiva. A diferencia de otras herramientas similares, Insomnia destaca por su interfaz limpia, su soporte nativo para OpenAPI y su capacidad de organizar las peticiones en colecciones reutilizables.

Con Insomnia puedes enviar peticiones HTTP, gestionar entornos y variables, configurar autenticación OAuth2, y validar respuestas frente a esquemas JSON. Es la herramienta ideal para equipos que trabajan con especificaciones OpenAPI y necesitan pasar rápidamente del diseño de la API a las pruebas funcionales.

Principales características de openapi2insomnia

openapi2insomnia es una CLI Node.js desarrollada por APIAddicts que convierte automáticamente especificaciones OpenAPI 3.0.x en colecciones Insomnia v5 listas para importar y ejecutar. Estas son sus principales características:

  • Generación automática de casos de prueba (TC): Crea un caso de prueba por cada código de respuesta definido en la operación, incluyendo el TC base de éxito, variantes por parámetro y TCs de error (400, 401, 403, 404).
  • Validación automática con scripts afterResponse: Cada caso de prueba incluye un script que valida el código de estado y el cuerpo de la respuesta contra el esquema definido en la especificación.
  • Soporte multi-entorno: Mediante un fichero de configuración (o2i.config.json), puedes generar una colección por entorno (DEV, PRE, PRO), cada una con su propia URL base, credenciales OAuth2 y opciones de generación.
  • Compatibilidad con OAuth2: Configura token URL, authorization URL, client ID y client secret por entorno directamente desde el fichero de configuración.
  • Modo minimal: Con la opción minimal_endpoints, genera únicamente el TC base de éxito por operación, ideal para exploraciones rápidas.
  • Soporte para oneOf/anyOf: Activa la opción generate_oneOf_anyOf para generar un conjunto de TCs por cada variante de esquema en el cuerpo de la petición.
  • Integración con Microcks: Añade automáticamente la cabecera X-Microcks-Response-Name a todas las peticiones para facilitar la integración con entornos de simulación.
  • Licencia LGPL v3: Proyecto de código abierto con licencia GNU Lesser General Public License v3.0.

¿Cómo empezar con openapi2insomnia?

Empezar con openapi2insomnia es muy sencillo. Solo necesitas Node.js 20 o superior instalado en tu sistema. A continuación, los pasos para comenzar:

1. Instalación global vía npm:

npm install -g openapi2insomnia

2. Convertir tu especificación OpenAPI:

o2i convert -i openapi.yaml -o collection.yaml

3. Usar una URL remota:

o2i convert -i https://api.example.com/openapi.yaml -o collection.yaml

4. Configurar múltiples entornos con un fichero o2i.config.json:

o2i convert -i openapi.yaml -c o2i.config.json

Una vez generada la colección en formato YAML, simplemente importala en Insomnia y tendrás todos tus endpoints listos para testear, con casos de éxito, errores y validación de esquemas incluidos.