Azure API Management acaba de presentar la compatibilidad con la versión preliminar de OpenAPI Specification v3, la versión más reciente del estándar de código abierto ampliamente utilizado de descripción de API. La implementación de la característica se basa en el SDK de OpenAPI.NET.

En esta entrada de blog vamos a explorar:

• Las ventajas de usar OpenAPI Specification para sus API.
• Cómo puede crear API a partir de documentos de OpenAPI Specification en Azure API Management.
• Cómo puede exportar sus API como documentos de OpenAPI Specification.
• El trabajo restante para el lanzamiento de disponibilidad general.

¿Por qué debería usar OpenAPI Specification para sus API?

OpenAPI Specification es un estándar industrial ampliamente adoptado. OpenAPI Initiative ha recibido el respaldo de más de 30 compañías, incluidas grandes corporaciones como Microsoft.

OpenAPI Specification le permite abstraer sus API de su implementación. Las definiciones de API son independientes de idioma.

También son fáciles de entender y, al mismo tiempo, precisas. Sus API se representan a través de archivos YAML o JSON, legibles tanto para humanos como para máquinas.

La amplia adopción de OpenAPI Specification ha dado lugar a un extenso ecosistema de herramientas. La funcionalidad de las herramientas va desde facilitar el proceso de colaboración para diseñar API hasta generar SDK de clientes e implementaciones de servidor en los lenguajes de programación más utilizados.

¿Cómo importar las definiciones de OpenAPI v3 Specification v3 en Azure API Management?

Si sus API están definidas en un archivo de OpenAPI Specification, puede importarlas fácilmente en Azure API Management. Azure Portal reconocerá automáticamente la versión correcta de sus archivos de OpenAPI Specification. Puede aprender cómo importar sus API a través de la interfaz visual siguiendo nuestro tutorial “Importación y publicación de la primera API.”

Alternativamente, puede importar API utilizando la llamada API de REST, con el parámetro de carga útil contentFormat establecido en openapi, openapi+json u openapi-link.

Durante la importación, si el campo servers de la especificación contiene varias entradas, API Management seleccionará la primera dirección URL HTTPS. Si no hay ninguna dirección URL HTTPS, se seleccionará la primera dirección URL HTTP. Si no hay ninguna dirección URL HTTP, la dirección URL del servicio back-end estará vacía.

La funcionalidad de importación tiene algunas restricciones. Por ejemplo, no admite los campos examples ni multipart/form-data.

¿Cómo exportar las definiciones de OpenAPI v3 Specification v3 en Azure API Management?

Con Azure API Management, también puede exportar fácilmente sus API en el formato de OpenAPI Specification v3.

Las especificaciones de la API se pueden descargar desde el portal para desarrolladores como archivos JSON o YAML. El portal para desarrolladores es un sitio web generado automáticamente y totalmente personalizable donde los visitantes pueden descubrir API, aprender a usarlas, probarlas de forma interactiva y, finalmente, registrarse para adquirir claves de API.

También puede exportar las especificaciones a través de la interfaz visual de Azure Portal o una llamada API de REST, con el parámetro de consulta de formato establecido en openapi-link.

¿Cómo empezar y qué viene a continuación?

Puede probar la funcionalidad actual en cuestión de minutos importando sus API desde los archivos de OpenAPI Specification. Antes de que la característica esté disponible con carácter general, implementaremos la exportación en formato JSON a través de una llamada API de REST. En los próximos meses, también agregaremos compatibilidad con la importación y exportación de OpenAPI Specification v3 en el SDK de PowerShell.

Díganos lo que piensa.