Compartir:
){kind=small}
Lorna es ingeniera de software con un incurable hábito bloguero. Intenta domar las palabras y el código a partes iguales.
OpenAPI facilita las integraciones
Tiempo de lectura: 3 minutos
Tomamos nuestra documentación para desarrolladores muy en serio, especialmente nuestra Referencia API. La documentación de referencia se genera a partir de una descripción legible por máquina de cada API, en formato OpenAPI de OpenAPI. Trabajar con un formato basado en texto y legible por máquina facilita el mantenimiento de la documentación. Eso es estupendo para nosotros, los encargados de la documentación, pero ¿cómo le ayuda a usted, el usuario? Me alegro de que lo preguntes.
Eche un vistazo a cualquiera de nuestras páginas de referencia de API. Allí hay un botón con la etiqueta "Descargar especificación OpenAPI 3" y, si hace clic en él, recibirá el regalo de YAML. También puede encontrar todas nuestras especificaciones en la carpeta definitions/ de nuestro repositorio Especificaciones de API repositorio GitHub.
El uso de un formato estándar de descripción de API como OpenAPI le da acceso a muchas herramientas diferentes que entienden estos archivos. Voy a mostrarte algunas de mis cosas favoritas para hacer con una especificación OpenAPI.
Cuando estás probando una API con la que no estás familiarizado, puede ser frustrante tratar de escarbar en la documentación para entender cómo armar una solicitud en particular. Postman admite la importación de archivos de especificaciones OpenAPI y los convierte en una colección de solicitudes de API ya preparadas. Es una forma brillante de probar una nueva API sin tener que pasar demasiado tiempo leyendo documentación y copiando nombres de campos en mi cliente HTTP.
Soy un gran fan de este enfoque y lo uso, con mucha frecuencia, incluso en APIs que conozco tan bien que podría escribir los comandos curl con los ojos vendados. Es una forma muy rápida de interactuar correctamente con una API y me resulta muy útil.
Cuando viajo, a veces me encuentro sin una conexión fiable a Internet. Si tengo el archivo de especificaciones OpenAPI localmente (spoiler: siempre tengo los archivos de especificaciones localmente, ¡trabajo mucho en este repo!), entonces puedo usar una de las herramientas de documentación OpenAPI para crear documentos que puedo usar en mi portátil.
Una opción es utilizar la herramienta que utilizamos nosotros mismos, esta es Renderizador Nexmo OAS. Es una herramienta de código abierto basada en Ruby que creamos y publicamos nosotros mismos. No está ligado a nuestras especificaciones, sin embargo, sobre todo lo uso para nuestras propias APIs, pero debería funcionar en cualquier archivo de especificaciones OpenAPI v3 válida.
El otro método que utilizo a veces es otra herramienta de código abierto, esta vez en NodeJS, llamada ReDoc. De nuevo, es útil para crear documentación HTML a partir de una especificación OpenAPI. ¡Prueba ambas opciones y luego elige tu favorita!
La descripción de una API contiene información sobre todos sus aspectos. Tanta información, de hecho, que podrías hacer una muy buena suplantación de esa API con todos los detalles que se incluyen.
Una muy buena suplantación de la API de una especificación OpenAPI es exactamente lo que Prisma de Stoplight proporciona. Es una herramienta NodeJS; instálala con npm e iníciala localmente, ¡y tendrás tu propia copia privada de la API de un archivo de especificaciones OpenAPI!
Esto es lo que más utilizo durante el desarrollo, cuando es posible que tenga que llamar al mismo punto final de la API varias veces para asegurarme de que estoy gestionando correctamente las distintas respuestas. Un servidor simulado es más rápido que una API remota y mucho más barato. Tampoco hay límites de velocidad. Para cualquiera que se integre con una API, herramientas como los servidores simulados suponen un gran impulso. Para nosotros, como proveedores de API, no es necesario construir o dar soporte a un sandbox para que la gente pueda desarrollar sus integraciones en un espacio seguro; lo obtenemos como beneficio secundario de usar OpenAPI.
He elegido tres cosas que creo que marcan una gran diferencia para los usuarios de API cuando su proveedor de API pone a su disposición las especificaciones de OpenAPI. Vonage no es particularmente notable en la publicación de descripciones de API; yo esperaría que la mayoría de los proveedores de API modernos hicieran lo mismo. Espero que tengas algunas ideas sobre lo que te gustaría probar para mejorar tu próxima integración de API. Háganos saber si ya está utilizando uno de estos enfoques, o cuál le gustaría probar a continuación.
¿Siente curiosidad por OpenAPI y nuestras herramientas? Aquí tiene más información:
Iniciativa OpenAPI: https://www.openapis.org
El mejor lugar para buscar herramientas para usar con OpenAPI: https://openapi.tools
Postman para importar una especificación para hacer una colección de peticiones a utilizar: https://postman.com
Prisma el servidor simulado: https://stoplight.io/open-source/prism
Más documentación específica de Vonage sobre OpenAPI, incluida información más detallada sobre el uso de Postman y Prism, y la generación de documentación: /comenzando/concepts/openapi