En esta ocasión nos vamos a centrar en las principales diferencias entre OpenAPI v3 y swagger, nombre con el que se conoce la v2. Asumimos, por tanto, que se tienen ciertos conocimientos en swagger. Si todavía no lo has hecho, te recomendamos leer el blog anterior, en el que se habló de OpenAPI v2 entre otras cosas.
Estructura del documento de definición con OpenAPI v3
OpenAPI
Info
Servers
Este elemento agrupa y hace innecesarios los elementos host, schemes y basepath. La URL base de cada host se especifica por completo en cada elemento del array de servidores. Como se pueden especificar tantos como sean necesarios podemos tener distintos protocolos, máquinas y contextos sirviendo la misma API.
Paths
RequestBody
Responses/Content
En la versión 3 seguimos disponiendo de la sección responses para describir las respuestas, pero esta contiene una subsección denominada content en la cual podemos definir un esquema y un ejemplo distinto en función del mime-type a devolver. Ya no es necesaria la configuración de formatos a nivel de API, se hace siempre a nivel de endpoint. Es algo más tedioso, pero a la vez más flexible. Permite, al igual que en swagger, definir distintos ejemplos en función del mime-type, aunque la definición de ejemplos con formatos distintos a JSON sigue siendo tediosa.
Rangos de respuestas
Servers
Links
Components
Schemas
Parameters
Responses
RequestBodies
Headers
No obstante hay que indicar que las cabeceras definidas en esta sección sólo pueden usarse en las respuestas. Si necesitamos definir una cabecera de entrada lo haremos de la misma forma que en swagger, es decir, como parámetro.
Examples
Links
SecuritySchemes
Herramientas para trabajar con OpenAPI v3
Hay que añadir, sin embargo, una nueva categoría de herramientas: los convertidores entre versiones. Existen convertidores online como Mermade swagger converter, que realiza la conversión de swagger a OpenAPI v3 subiendo el archivo de definición o mediante copy-paste en la propia interfaz.
También existe una potente herramienta de conversión online, APImatic Transformer, que convierte entre múltiples formatos. El inconveniente es que es de pago y sólo permite un número limitado de conversiones gratuitas por día, pero es una opción muy interesante por la cantidad de formatos soportados.
En este sentido también existe una utilidad en forma de paquete npm: api-spec-converter. Soporta varios formatos, aunque no tantos como Transformer. Se puede usar mediante línea de comandos, desde una aplicación node.js, o mediante un script embebido en el HTML de un frontal, lo que la hace bastante versátil.
Conclusiones
La curva de aprendizaje de OpenAPI es algo más larga que la de swagger, especialmente si no se tiene experiencia previa con este, pero los resultados a la hora de definir son, en general, mejores.
En general se puede decir que OpenAPI v3 mejora a su predecesora, aunque aún le queda camino por recorrer.
Enlaces de interés
Blog realizado por David Marín.
¡Habla con nuestros expertos!
