¿Cómo se integra OpenAPI con Postman? #

Postman es una de las plataformas más utilizadas para el desarrollo, las pruebas y la colaboración en torno a las API. Su profunda integración con OpenAPI facilita importar definiciones de API existentes, generar colecciones para pruebas y exportar colecciones de Postman de vuelta al formato OpenAPI. Para los equipos que utilizan OpenAPI para el diseño de API y Postman para las pruebas y la colaboración, comprender esta integración es esencial para construir un flujo de trabajo de desarrollo de API eficiente.

Importar un documento OpenAPI en Postman #

El punto de integración más común es importar un documento OpenAPI 2.0, 3.0 o 3.1 en Postman para generar una colección de solicitudes. Esto puede hacerse desde la interfaz de Postman o mediante la API de Postman.

Desde la interfaz de Postman #

1. Abre Postman y haz clic en Import en la esquina superior izquierda.
2. Arrastra y suelta tu archivo OpenAPI en YAML o JSON, pega el texto del documento o proporciona la URL del documento alojado.
3. Postman analiza el documento y ofrece opciones de configuración, entre ellas si se debe generar una colección, una definición de API o ambas.
4. Haz clic en Import y Postman crea una colección con carpetas organizadas por etiqueta y solicitudes para cada operación.

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

Mediante la API de Postman #

Para los flujos de trabajo automatizados, la API REST de Postman permite importar documentos OpenAPI de forma programática. Esto resulta útil en pipelines de CI/CD donde el documento OpenAPI se actualiza con frecuencia y la colección de Postman debe mantenerse sincronizada:

curl -X POST https://api.getpostman.com/apis \
  -H "X-Api-Key: $POSTMAN_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"api": {"name": "My API", "schema": {"type": "openapi3", "input": "<openapi_json>"}}}'

El API Builder de Postman #

El API Builder de Postman ofrece un flujo de trabajo de primer nivel para trabajar con documentos OpenAPI dentro de Postman:

1. Crea una API en el API Builder de Postman y adjunta un documento OpenAPI como su definición.
2. Postman valida el documento frente a la especificación OpenAPI e informa de los errores en línea.
3. A partir de la definición, Postman puede generar una colección (para pruebas), generar stubs de servidor (en varios lenguajes) y generar documentación.
4. Cada vez que cambia el documento OpenAPI, Postman detecta el cambio y ofrece regenerar la colección dependiente.

Esto convierte al API Builder en una herramienta ligera de diseño y gobernanza, además de sus capacidades de pruebas.

Generar y ejecutar pruebas a partir de OpenAPI #

Una de las integraciones más potentes es la capacidad de Postman para generar scripts de prueba a partir de un documento OpenAPI. Con el Collection Runner de Postman y Newman (la CLI de Postman), los equipos pueden:

1. Importar el documento OpenAPI para crear una colección.
2. Añadir scripts de prueba a las solicitudes, ya sea manualmente o con los fragmentos de prueba integrados de Postman.
3. Ejecutar la colección en cualquier entorno (desarrollo, preproducción, producción) con el Collection Runner o Newman:

npm install -g newman
newman run collection.json --environment environment.json

Este flujo de trabajo se utiliza habitualmente para pruebas de humo, pruebas de regresión y pruebas de integración en pipelines de CI/CD.

Entornos de Postman y servidores de OpenAPI #

El campo servers de OpenAPI se corresponde de forma natural con los entornos de Postman. Al importar un documento OpenAPI, Postman puede crear variables de entorno para cada URL de servidor, por ejemplo, {{baseUrl}} para el servidor de producción y un archivo de entorno independiente para preproducción. Esto facilita ejecutar la misma colección en distintos entornos sin modificar las solicitudes.

Exportar colecciones de Postman a OpenAPI #

Las colecciones de Postman también pueden exportarse de vuelta al formato OpenAPI, aunque la calidad del resultado depende de lo bien estructurada que esté la colección. Postman permite exportar como OpenAPI 3.0 desde el API Builder cuando hay una definición vinculada a la colección.

Herramientas como postman-to-openapi ofrecen una conversión más configurable para los equipos que mantienen sus definiciones de API principalmente en colecciones de Postman y quieren generar un documento OpenAPI con fines de documentación o gobernanza.

Postman y la gobernanza de OpenAPI #

Postman se integra con Postman Flows y con la API de Postman para admitir flujos de trabajo de gobernanza:

• Validación de esquemas: Postman valida los documentos OpenAPI frente a la especificación y puede bloquear la publicación de documentos no válidos.
• Seguimiento y notificaciones de cambios: los miembros del equipo pueden seguir una definición de API y recibir una notificación cuando cambie.
• Control de versiones: Postman admite varias versiones de una definición de API, lo que permite a los equipos mantener documentos OpenAPI v1 y v2 en paralelo.

Para las organizaciones que usan Postman Enterprise, las redes de API privadas permiten publicar las API internas, descritas mediante documentos OpenAPI, en un catálogo interno con función de búsqueda, similar a un portal para desarrolladores.

Usar Postman Monitors con OpenAPI #

Postman Monitors ejecutan colecciones de Postman de forma programada e informan de los fallos. Para los equipos que importan documentos OpenAPI para crear colecciones, los monitores ofrecen una forma ligera de verificar de manera continua que la API de producción coincide con su descripción OpenAPI.

Limitaciones y consideraciones #

Aunque la integración entre Postman y OpenAPI es potente, hay algunas limitaciones que conviene tener en cuenta:

• Generación del cuerpo de la solicitud: el generador de colecciones de Postman no siempre produce un cuerpo de solicitud de ejemplo bien completado a partir de los esquemas de OpenAPI. Con frecuencia, los equipos deben rellenar manualmente los valores de ejemplo en las solicitudes generadas.
• Configuración de la autenticación: los esquemas de seguridad de OpenAPI se importan, pero puede ser necesario configurar manualmente las credenciales en los entornos de Postman.
• Sincronización bidireccional: los cambios realizados en una colección de Postman no se propagan automáticamente de vuelta al documento OpenAPI. La integración es principalmente unidireccional (OpenAPI → Postman).
• Construcción dinámica de solicitudes: las colecciones de Postman son estáticas. Para patrones de prueba dinámicos (pruebas parametrizadas, pruebas basadas en datos) se requieren scripts adicionales en los scripts de pre-solicitud y de prueba de Postman.

El futuro nativo de OpenAPI en Postman #

Postman ha estado invirtiendo para que OpenAPI sea un ciudadano de primera clase en toda su plataforma. Con el API Builder de Postman, la plataforma se posiciona como una herramienta para todo el ciclo de vida de las API: desde el diseño (edición de OpenAPI), pasando por las pruebas (colecciones, monitores), hasta la publicación (documentación). Para los equipos que ya usan Postman para sus pruebas, esto lo convierte en un hogar natural para la gobernanza de API basada en OpenAPI, sin necesidad de herramientas adicionales.

Conclusión #

La integración de Postman con OpenAPI abarca todo el ciclo de vida del desarrollo de API: importar definiciones de API para generar colecciones, ejecutar pruebas en servidores reales, gestionar varias versiones de una API y publicar documentación. Ya se utilice para pruebas exploratorias manuales o para pipelines de CI/CD automatizados mediante Newman, Postman y OpenAPI ofrecen juntos un flujo de trabajo completo para los equipos de API. Comprender los puntos de integración, y sus limitaciones, ayuda a los equipos a sacar el máximo partido de ambas herramientas.

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