Como desarrollador que trabaja con API, es probable que esté familiarizado con Postman, una herramienta popular para probar y documentar sus endpoints. Sin embargo, cuando se trata de compartir la documentación de su API en un formato estandarizado como OpenAPI 3.0, es posible que se sienta perdido.
¡No tema! Esta guía completa lo guiará a través del proceso de conversión de sus colecciones de Postman a especificaciones de OpenAPI 3.0, con un enfoque en el popular paquete npm postman-to-openapi.
¿Por qué convertir Postman a OpenAPI?
Antes de comenzar, repasemos rápidamente por qué querría convertir sus colecciones de Postman a OpenAPI:
- Estandarización: OpenAPI es un estándar de la industria para describir las API RESTful, lo que garantiza que su documentación sea coherente y fácilmente comprensible para otros desarrolladores.
- Interoperabilidad: muchas herramientas y plataformas admiten OpenAPI, lo que facilita la integración con otros sistemas y servicios.
- Documentación: OpenAPI proporciona un formato claro y legible para la documentación de la API, lo que facilita que otros comprendan y utilicen su API.
- Generación de código: puede utilizar las especificaciones de OpenAPI para generar bibliotecas de cliente y stubs de servidor, lo que agiliza su proceso de desarrollo.
¡Ahora, exploremos cómo hacer que esta conversión suceda!
Usar postman-to-openapi: una guía paso a paso
El paquete npm postman-to-openapi es una herramienta poderosa para convertir colecciones de Postman a especificaciones de OpenAPI 3.0. Aquí hay una guía paso a paso sobre cómo usarlo:
Paso 1: Instale el paquete postman-to-openai a través de npm
Primero, deberá instalar el paquete. Abra su terminal y ejecute:
npm install postman-to-openapi
O si prefiere yarn:
yarn add postman-to-openapi
Paso 2: Usar postman-to-openapi en Node.js
Una vez instalado, puede usar el paquete en su proyecto Node.js. Aquí hay un ejemplo simple:
const postmanToOpenApi = require('postman-to-openapi')
const postmanCollection = './path/to/your/collection.json'
const outputFile = './output/openapi.yml'
async function convertCollection() {
try {
const result = await postmanToOpenApi(postmanCollection, outputFile, {
defaultTag: 'General'
})
console.log(`OpenAPI specs: ${result}`)
} catch (err) {
console.error('Conversion failed:', err)
}
}
convertCollection()
Este script convertirá su colección de Postman a un archivo YAML de OpenAPI 3.0.
Paso 3: Uso personalizado de postman-to-openapi
El paquete postman-to-openapi ofrece varias opciones para personalizar su conversión. Aquí hay algunos útiles:
defaultTag: Establezca una etiqueta predeterminada para todas las operaciones (predeterminado: 'default').outputFormat: Elija entre 'yaml' o 'json' (predeterminado: 'yaml').includeAuthInfoInExample: Incluya información de autenticación en los ejemplos (predeterminado: false).
Modifiquemos nuestro script para usar estas opciones:
const postmanToOpenApi = require('postman-to-openapi')
const postmanCollection = './path/to/your/collection.json'
const outputFile = './output/openapi.json'
async function convertCollection() {
try {
const result = await postmanToOpenApi(postmanCollection, outputFile, {
defaultTag: 'MyAPI',
outputFormat: 'json',
includeAuthInfoInExample: true
})
console.log(`OpenAPI specs: ${result}`)
} catch (err) {
console.error('Conversion failed:', err)
}
}
convertCollection()
Este script generará un archivo JSON con información de autenticación incluida en los ejemplos y todas las operaciones etiquetadas como 'MyAPI'.
¿Qué sucede si no quiero usar el paquete postman-to-openapi?
Si bien el paquete postman-to-openapi es excelente para conversiones sencillas, a veces es posible que necesite más control o tenga requisitos específicos. Exploremos algunas técnicas avanzadas.
Opción 1. Usar APIDog para la conversión de Postman a OpenAPI
APIDog es otra excelente herramienta que puede ayudarlo a convertir colecciones de Postman a formato OpenAPI. Aquí hay una guía rápida sobre cómo usarlo:
- Inicie sesión en APIDog y vaya al menú "Settings".
- Seleccione "Import" de las opciones.
- Elija el archivo de colección de Postman que desea importar. APIDog importará y convertirá su colección, lo que le permitirá ver y editar la documentación de la API resultante.
4. Haga clic en el botón Export Data y elija exportar a formato OpenAPI 3.0.
Pero espere, APIDog no es simplemente un convertidor de colecciones de Postman a formato OpenAPI. Es una alternativa fácil de usar que le hace olvidarse de pagar por Postman Enterprise.
APIDog ofrece funciones adicionales como pruebas de API y servidores mock, lo que la convierte en una solución integral para el desarrollo y la documentación de API. Esto es lo que obtiene de APIDog en lugar de suscribirse a Postman por $19/mes:
- Creación de API ilimitada
- Sin restricciones de flujo y ejecuciones ilimitadas de Collection Runner
- Llamadas API ilimitadas
- Llamadas ilimitadas al servidor API Mock
¡Todo esto está disponible en la versión gratuita de APIDog!
Además, por solo $9/mes, puede acceder a todas las funciones del plan profesional de Postman que le costarían $39/mes.
Opción 2. Usar la API de Postman para la conversión
Postman en sí ofrece una API que puede transformar colecciones a formato OpenAPI. Aquí le mostramos cómo puede usarlo:
- Obtenga su clave de API de Postman de la configuración de su cuenta.
- Use el siguiente comando curl (reemplace los marcadores de posición con sus valores reales):
curl --location --request GET 'https://api.getpostman.com/collections/{{collectionId}}/transformations' \
--header 'Content-Type: application/json' \
--header 'x-api-key: {{postman-api-key}}'
- La respuesta contendrá la especificación OpenAPI. Puede guardar esto en un archivo para su uso posterior.
Opción 3. Herramientas en línea para la conversión de Postman a OpenAPI
Si prefiere una solución rápida y sin código, puede usar algunas herramientas en línea para una conversión rápida. Aquí le mostramos cómo usarlo:
- Elija de una de las herramientas en línea gratuitas disponibles.
- Cargue su archivo JSON de colección de Postman o pegue la URL de la colección.
- Haga clic en "Convert" y descargue la especificación OpenAPI resultante.
Este método es excelente para conversiones únicas o cuando no desea configurar un entorno de desarrollo.
Cómo convertir Postman a OpenAPI sin problemas: consejos y mejores prácticas
Incluso con las mejores herramientas, puede encontrar algunos contratiempos. Estos son algunos problemas comunes y sus soluciones:
- Dividir colecciones: divida las colecciones grandes en partes más pequeñas y manejables. Este enfoque permite una conversión y un mantenimiento más fáciles de las especificaciones OpenAPI resultantes.
- Usar carpetas: organice su colección de Postman usando carpetas para crear una estructura lógica. Esto ayudará a generar una especificación OpenAPI bien organizada y facilitará la navegación.
- API Transformer: utilice herramientas como API Transformer, que pueden manejar grandes colecciones de Postman y convertirlas en especificaciones OpenAPI de manera eficiente.
- Validación de OpenAPI: valide su especificación OpenAPI después de la conversión para asegurarse de que sea correcta y completa. Este paso es crucial para identificar cualquier problema que pueda haber surgido durante el proceso de conversión.
Por lo tanto, para garantizar un proceso de conversión sin problemas, tenga en cuenta estos consejos:
- Limpie su colección de Postman: antes de la conversión, revise su colección en busca de inconsistencias o elementos innecesarios.
- Use nombres descriptivos: asegúrese de que sus endpoints, parámetros y respuestas tengan nombres claros y descriptivos en Postman.
- Incluya ejemplos: agregue ejemplos de respuestas en Postman para enriquecer su documentación de OpenAPI.
- Organice con carpetas: use carpetas en Postman para agrupar lógicamente sus endpoints, lo que se traducirá en etiquetas en OpenAPI.
- Valide la salida: después de la conversión, use un validador de OpenAPI para asegurarse de que la especificación resultante sea válida.
Conclusión
Convertir colecciones de Postman a especificaciones de OpenAPI es un paso crucial para estandarizar la documentación de la API y garantizar una integración perfecta con otros sistemas.
Siguiendo los pasos descritos en esta guía, puede convertir de manera eficiente sus colecciones de Postman y aprovechar los beneficios que ofrece OpenAPI.
Preguntas frecuentes (FAQ)
P: ¿Cuál es el principal beneficio de convertir colecciones de Postman a especificaciones de OpenAPI?
R: El principal beneficio es la estandarización, que permite una integración más fácil con otros sistemas y herramientas.
P: ¿Puedo usar herramientas en línea para la conversión de Postman a OpenAPI?
R: Sí, hay herramientas en línea como p2o.defcon007.com y APIDog disponibles para convertir colecciones de Postman a especificaciones de OpenAPI.
P: ¿Cómo manejo las grandes colecciones de Postman durante la conversión?
R: Las colecciones grandes se pueden dividir en partes más pequeñas, organizarse usando carpetas o convertirse usando herramientas como API Transformer.
P: ¿Es necesario validar la especificación OpenAPI después de la conversión?
R: Sí, validar la especificación OpenAPI después de la conversión es crucial para asegurarse de que sea correcta y completa.