¿Qué es una especificación de OpenAPI?

La especificación de OpenAPI, anteriormente conocida como Swagger, describe varios aspectos de una API. Una especificación de OpenAPI (especificación) describe los puntos de conexión, los parámetros y las respuestas de la API. Las especificaciones de OpenAPI se escriben en YAML o JSON y las usan herramientas para generar documentación, casos de prueba y bibliotecas cliente. Al tener una especificación de OpenAPI, los desarrolladores de API pueden asegurarse de que su API se describe con precisión, es más accesible y fácil de integrar en una amplia gama de aplicaciones y servicios.

Este es el motivo por el que debe considerar tener una especificación de OpenAPI para la API:

• Documente una API de forma estandarizada. Documente una especificación de API en un formato coherente y legible.
• Genere un SDK de cliente. Use herramientas como Kiota para automatizar la generación de bibliotecas cliente en varios lenguajes de programación.
• Cree una API ficticia. Cree servidores ficticios basados en la especificación de API, lo que le ayuda durante las primeras fases de desarrollo cuando la API real aún no se ha implementado.
• Mejorar la colaboración. Proporcione distintos equipos (front-end, back-end, QA) con una comprensión clara de las funcionalidades y limitaciones de la API, lo que ayuda a los nuevos miembros del equipo a ponerse al día rápidamente.
• Simplificar pruebas y validación. Automatice la validación de solicitudes y respuestas de API conforme a la especificación, lo que facilita la identificación de discrepancias.
• Integre con las herramientas de gestión de API. Integre, implemente y supervise fácilmente sus API con muchas herramientas y puertas de enlace para la administración de API, como Azure API Center y Azure API Management.
• Simplifique la configuración de la puerta de enlace de API. Use especificaciones de OpenAPI para configurar puertas de enlace de API y automatizar tareas como el enrutamiento, las transformaciones y la configuración de uso compartido de recursos entre orígenes.

Mediante el uso de especificaciones de OpenAPI, puede crear API que estén bien diseñadas y documentadas de forma coherente. También son más fáciles de mantener y usar tanto internamente como por consumidores externos.

¿Aún no tiene una especificación de OpenAPI?

Escribir una especificación a mano para una API que ya existe lleva tiempo y se desvía de lo que realmente hace la API. Otra opción es registrar lo que devuelve la API y generar la especificación a partir de eso.

Approach	Lo que obtienes	¿Qué hay que ver?
Escríbalo a mano	Control total sobre descripciones y ejemplos	Lleva tiempo y se desfasa de la API real.
Genéralo a partir de anotaciones de código	Una especificación que se mantiene sincronizada con tu código	Necesita acceso al código de la API y el marco tiene que admitirlo.
Generarlo a partir del tráfico registrado	Especificación para cualquier API a la que puede llamar, incluidas las que no posee	Solo cubre las solicitudes que registró, por lo que utiliza las partes de la API que necesita.

Dev Proxy registra las solicitudes y respuestas entre la aplicación y una API y genera una especificación de OpenAPI a partir de ellas. Para conocer los pasos, consulte Generar una especificación OpenAPI.

Paso siguiente

Genera una especificación de OpenAPI