Header Ads Widget

Ticker

6/recent/ticker-posts

¿Qué hay de nuevo en OpenAPI 3.1.0?

 


OpenAPI obtiene una actualización con compatibilidad de esquema JSON, soporte de webhook y correcciones cosméticas.

Poco más de un año después del lanzamiento de OAS 3.0.3 - y cinco meses después de OAS 3.1.0 RC1's - OAS 3.1.0 finalmente ha salido al aire . Esta es la última revisión importante de la Iniciativa OpenAPI a la rama OEA 3.0. A pesar de esto, los desarrolladores de la especificación quieren que la actualización se sienta incremental para los nuevos usuarios. Los usuarios corporativos que dependen de la OEA deberían sentirse más cómodos con una adopción rápida. Si bien las convenciones de nomenclatura semántica dictan el salto a OAS 4.0, el salto desalentaría la adopción rápida de cambios críticos.

Si bien el consorcio siempre avanza en el desarrollo, los lanzamientos tienden a espaciarse durante meses o años. Los adoptantes deben sentirse cómodos con esta última versión. Afortunadamente, hay muchas novedades actualizadas para que los desarrolladores las desempaqueten. ¿Qué ha cambiado exactamente?

Compatibilidad completa con el esquema JSON

Los cambios bajo el esquema JSON encabezan esta nueva versión de la OEA. JSON es el formato predeterminado para los documentos OpenAPI (aparte de YAML) y se ha vuelto inmensamente importante para los desarrolladores de todo el mundo. Desafortunadamente, las deficiencias de soporte y la estandarización dudosa han obstaculizado la utilidad de JSON Schema y estructuras de datos similares. Las extensiones de esquema han sido el producto de numerosos enfoques.

OAS 3.1.0 resuelve muchos de estos problemas mediante una compatibilidad del 100% con el último borrador de JSON Schema (2020-12). Esta versión enfatiza la estandarización de la extensión del esquema. La inclusión de nuevos vocabularios refuerza este enfoque basado en estándares, lo que impacta en procesos como la creación de código, el desarrollo de la interfaz de usuario y la documentación. Dado que OpenAPI en sí mismo defiende la programación estandarizada para las API modernas, este cambio es filosófica y funcionalmente relevante. El esquema JSON también seguirá siendo una guía útil para la validación.

Nota: Estos vocabularios de esquema ahora se denominan "dialectos de esquema" en la versión de lanzamiento.

Las descripciones de carga de archivos se han modificado al mismo tiempo que los nuevos desarrollos de JSON Schema. La Iniciativa OpenAPI advierte que esto puede ser un cambio radical, incluso dentro de la construcción estable. En general, una mayor integración con JSON Schema constituye una oportunidad para mejorar la definición del comportamiento dentro de la OEA. En consecuencia, la adición del jsonSchemaDialectcampo de nivel superior facilita las declaraciones de valores predeterminados para los objetos de esquema.

Mejores descripciones de webhooks

Muchas empresas utilizan webhooks para compartir datos entre aplicaciones. Muchos de estos webhooks (como los que utilizan Stripe y GitHub , por ejemplo) se desarrollan internamente; sin embargo, no siempre se pueden administrar en la red corporativa.

Esta red está sujeta a interrupciones ocasionales, ya que ningún ecosistema disfruta del 100% de tiempo de actividad . Aquellos que aprovechan los webhooks servidor-servidor intermediarios deben administrarlos de forma remota según sea necesario. Esto es especialmente relevante en el clima actual. Por tanto, estos webhooks se gestionan fuera de banda. Es igualmente importante tener en cuenta estos Webhooks especiales en consecuencia, ya que entregan datos y envían eventos de formas únicas.

OAS 3.1.0 introduce un nuevo elemento de nivel superior para describir webhooks fuera de banda. Lo mismo ocurre con los webhooks que están registrados externamente. Los desarrolladores pueden describir los parámetros, el propósito y las interacciones de cada webhook más allá de lo que se genera automáticamente. Las API han disfrutado de esta funcionalidad bajo la OEA durante algún tiempo .

Las descripciones pueden ser largas o cortas. Además, algunos objetos permiten resúmenes. Se instituyeron cambios basados ​​en la descripción para aumentar la claridad del documento, al tiempo que proporciona un mayor contexto para cada tecnología en cuestión.

Saluda a la identificación estandarizada

En la versión anterior de la OEA, la identificación del objeto de la licencia para las API expuestas tenía dos partes : un nombre y una URL. Estos campos son ambas cadenas. Se requería el nombre de la licencia para cada API, mientras que las URL de las licencias de API tenían que estar en formato URL. Los objetos de licencia también se podían ampliar según la especificación.

OAS 3.1.0 ahora admite la identificación de licencias API a través del identificador SPDX estándar. El estándar SPDX emplea una lista de licencias , que cataloga los nombres completos de las licencias, los identificadores, la libertad de FSF y la aprobación de OSI. Con eso viene cualquier excepción de licencia notada e identificadores abreviados para su código fuente.

La estandarización SPDX también emplea archivos de datos más limpios y legibles por máquina. Las URL incluidas son canónicas y permanentes, por lo que no hay riesgo de utilizar un enlace incorrecto. El estándar SPDX es vivo, lo que significa que ciertos componentes están sujetos a depreciación o reemplazo con el tiempo. Este estándar de identificación admitido está respaldado por la Fundación Linux.

Reutilización más sencilla

El PathItemsobjeto ahora es opcional bajo OEA 3.1.0. Anteriormente, algunos usuarios se quejaban de que las mejores prácticas no estaban claras en torno al almacenamiento o referencia de rutas externas. Además, el $refcampo era insuficiente para hacer referencia y mantener elementos de ruta en componentes. La falta de un componente reutilizable para PathItemssignificaba que las $refpropiedades tenían que apuntar a recursos externos. A veces esto era complicado. También hizo que la documentación fuera menos manejable.

Los reutilizables PathItemsahora se pueden describir en el componentsobjeto. El beneficio es la creación más sencilla de bibliotecas de componentes reutilizables. Además, las API que utilizan certificados de seguridad de cliente ahora pueden tener descripciones para una mayor transparencia.

Cambios varios

Al igual que con cualquier versión nueva, hay mucho enfoque en la limpieza. OAS 3.1.0 ha trabajado para solucionar muchos problemas persistentes que persisten en la versión 3.0.3 y anteriores. Algunos enlaces ahora tienen ubicaciones más precisas; en consecuencia, los URI y las URL disfrutan de una resolución de referencia relativa renovada. Algunos prefijos de extensiones de especificación se han reservado para las definiciones de la iniciativa OpenAPI.

Por último, se han agregado una serie de aclaraciones sobre los valores de los parámetros, los objetos de referencia, los ejemplos de documentación, las descripciones y los estándares de nomenclatura.

En general, la última actualización de OEA trae numerosos cambios en la calidad de vida del partido. La Iniciativa afirma que los comentarios de los desarrolladores jugaron un papel clave en la determinación de prioridades y soluciones. Se anima a los usuarios a actualizar con la garantía de que no será una empresa importante, ni requerirá extensas modificaciones.

Para una mirada más profunda a las nuevas características en OAS 3.1.0, vea a los colaboradores de OpenAPI Darrel Miller y Ron Ratovsky presentar las actualizaciones aquí:

Publicar un comentario

0 Comentarios