¿Cómo se puede usar OpenAPI para generar colecciones de Postman?

¿Cómo se puede usar OpenAPI para generar colecciones de Postman? #

Postman es la herramienta más utilizada para probar y explorar API. Una colección de Postman es un conjunto organizado de solicitudes a una API que los equipos usan para pruebas manuales, ejecuciones de pruebas automatizadas, documentación e incorporación de nuevos miembros. En lugar de crear las colecciones a mano —introduciendo individualmente la URL, los parámetros, los encabezados y el cuerpo de cada endpoint—, los equipos pueden generarlas automáticamente a partir de un documento OpenAPI. Este enfoque ahorra mucho tiempo, garantiza que la colección se mantenga sincronizada con la especificación de la API y proporciona un punto de partida coherente para escribir pruebas.

¿Por qué generar colecciones a partir de OpenAPI? #

Mantener manualmente una colección de Postman junto a un documento OpenAPI genera duplicación y desfase. A medida que la API evoluciona —se añaden nuevas operaciones, cambian los parámetros, se actualizan los cuerpos de las solicitudes—, ambos documentos deben actualizarse de forma independiente. Generar la colección desde OpenAPI resuelve este problema al convertir el documento OpenAPI en la única fuente de verdad:

  • Cada operación del documento OpenAPI se convierte en una solicitud de la colección.
  • Las definiciones de parámetros se convierten en parámetros de consulta, de ruta y de encabezado ya rellenados.
  • Los esquemas del cuerpo de la solicitud se convierten en cuerpos de solicitud de ejemplo.
  • Los esquemas y ejemplos de respuesta se adjuntan a las solicitudes como referencia.
  • Los esquemas de autenticación del documento OpenAPI se traducen a la configuración de autorización de Postman.

Método 1: importar directamente en Postman #

El enfoque más sencillo es importar el documento OpenAPI directamente en Postman:

  1. Abre Postman y haz clic en Import en la esquina superior izquierda.
  2. Selecciona tu archivo OpenAPI en YAML o JSON, o pega la URL del documento.
  3. Postman ofrece dos modos de importación:
    • API: importa el documento como una definición de API en el API Builder, desde el cual se pueden generar colecciones y mantenerlas sincronizadas.
    • Collection: genera directamente una colección independiente.
  4. Selecciona Postman Collection y haz clic en Import.

Postman asigna los campos de OpenAPI a la estructura de la colección:

  • tags → nombres de carpeta dentro de la colección
  • paths[path][method].summary → nombre de la solicitud
  • paths[path][method].description → descripción de la solicitud
  • parameters → parámetros de consulta, de ruta y de encabezado ya rellenados
  • requestBody → cuerpo de la solicitud (JSON, formulario, multipart)
  • servers[0].url → variable de URL base
  • security → configuración de autorización

La colección resultante se puede usar de inmediato para pruebas exploratorias.

Método 2: openapi-to-postmanv2 (CLI) #

openapi-to-postmanv2 es la biblioteca oficial de código abierto de Postman, escrita para Node.js, para la conversión programática. Es el mismo motor que usa internamente la interfaz de importación de Postman y resulta adecuado para pipelines de automatización.

Instalación #

npm install -g openapi-to-postmanv2

Uso #

openapi2postmanv2 -s openapi.yaml -o collection.json -p

La opción -p activa el formato legible (“pretty print”) para obtener una salida JSON más fácil de leer. El resultado es un archivo JSON de Postman Collection v2.1 que se puede importar en Postman o ejecutar directamente con Newman.

Uso programático #

const Converter = require('openapi-to-postmanv2');
const fs = require('fs');

const openapiContent = fs.readFileSync('openapi.yaml', 'utf8');

Converter.convert({ type: 'string', data: openapiContent }, {}, (err, result) => {
  if (result.result) {
    fs.writeFileSync('collection.json', JSON.stringify(result.output[0].data, null, 2));
  }
});

Opciones de conversión #

El conversor admite un amplio conjunto de opciones para controlar la salida:

  • folderStrategy: organiza las solicitudes por etiqueta (Tags) o por ruta (Paths).
  • requestNameSource: usa el summary de la operación o el operationId como nombre de la solicitud.
  • parametersResolution: define cómo resolver los esquemas $ref: Schema (usa las descripciones del esquema) o Example (usa valores de ejemplo).
  • exampleParametersResolution: usa los valores example del esquema o los genera a partir del esquema.
  • enableOptionalParameters: incluye los parámetros opcionales como parámetros deshabilitados en la colección.

Método 3: API de Postman (importación programática) #

Para pipelines de CI/CD en los que la colección debe actualizarse automáticamente en un espacio de trabajo de Postman cada vez que cambia el documento OpenAPI, la API de Postman permite crear y actualizar colecciones de forma programática:

# Convert OpenAPI to Postman collection
openapi2postmanv2 -s openapi.yaml -o collection.json -p

# Upload to Postman workspace
curl -X POST https://api.getpostman.com/collections \
  -H "X-Api-Key: $POSTMAN_API_KEY" \
  -H "Content-Type: application/json" \
  -d @collection.json

Para actualizar una colección existente (y evitar duplicados en cada ejecución):

curl -X PUT https://api.getpostman.com/collections/$COLLECTION_ID \
  -H "X-Api-Key: $POSTMAN_API_KEY" \
  -H "Content-Type: application/json" \
  -d @collection.json

Este patrón se puede integrar en GitHub Actions u otros sistemas de CI para mantener actualizado el espacio de trabajo de Postman tras cada merge a la rama principal.

Método 4: Redocly CLI #

Redocly CLI ofrece un flujo de trabajo openapi a bundle que puede combinarse con herramientas de conversión. Aunque Redocly no exporta colecciones de Postman de forma nativa, se utiliza habitualmente en una fase previa para agrupar documentos OpenAPI de varios archivos en un único archivo antes de pasarlos al conversor de Postman.

Ejecutar las colecciones generadas con Newman #

Newman es el ejecutor de colecciones de Postman para la CLI. Una vez generada una colección a partir del documento OpenAPI, se puede ejecutar en cualquier entorno:

npm install -g newman

newman run collection.json \
  --environment environment.json \
  --reporters cli,junit \
  --reporter-junit-export results.xml

Esto permite realizar pruebas de regresión automatizadas en pipelines de CI/CD. La salida XML de JUnit se integra con plataformas de CI como Jenkins, GitHub Actions y GitLab CI para mostrar los resultados de las pruebas como parte del informe de compilación.

Enriquecer las colecciones generadas con pruebas #

Las colecciones generadas contienen solicitudes, pero no scripts de prueba. Para que resulten útiles en la validación automatizada, es necesario añadir scripts de prueba a cada solicitud. Se pueden escribir manualmente en Postman o añadirse de forma programática mediante la API de colecciones de Newman o el Postman Collection SDK:

// Test script added to a request
pm.test("Status code is 200", () => {
  pm.response.to.have.status(200);
});

pm.test("Response has required fields", () => {
  const body = pm.response.json();
  pm.expect(body).to.have.property('id');
  pm.expect(body).to.have.property('email');
});

Una estrategia práctica consiste en generar la colección en cada ejecución de CI (para asegurar que refleje el documento OpenAPI más reciente), pero mantener los scripts de prueba por separado en un entorno de Postman o como una capa de scripts aplicada sobre la colección base generada.

Mantener las colecciones sincronizadas #

El principal desafío de las colecciones generadas es mantenerlas actualizadas a medida que evoluciona el documento OpenAPI. Prácticas recomendadas:

  • Regenerar en cada merge: usa un paso de CI para regenerar la colección y enviarla a Postman mediante la API cada vez que cambie el documento OpenAPI.
  • Usar entornos para las URL base: guarda la URL base como una variable de entorno de Postman ({{baseUrl}}) para que la colección funcione en desarrollo, preproducción y producción.
  • Separar lo generado de lo escrito a mano: mantén dos colecciones: una generada (actualizada automáticamente) y otra curada (con scripts de prueba) que se concilia periódicamente con la versión generada.

Conclusión #

Generar colecciones de Postman a partir de documentos OpenAPI elimina el esfuerzo manual de mantener dos descripciones paralelas de la API. Ya sea mediante la importación integrada de Postman, la CLI openapi-to-postmanv2 o la API de Postman para actualizaciones programáticas, los equipos pueden mantener sus espacios de trabajo de pruebas sincronizados con la especificación de API de referencia. Combinado con Newman para la integración con CI/CD, este flujo de trabajo pone al alcance de cualquier equipo que mantenga un documento OpenAPI las pruebas de API automatizadas y basadas en la especificación.

Última actualización: 30 de abril de 2026.

Este sitio web no está afiliado a la OpenAPI Initiative.