introduction

L’OpenAPI Initiative (OAI), un consortium d’experts du secteur tournés vers l’avenir qui se concentrent sur la normalisation de la classification et de la description des API, a publié la spécification OpenAPI 3.1.0 en février. Cette nouvelle version introduit une meilleure prise en charge des webhooks et ajoute une compatibilité à 100% avec le dernier projet (2020-12) de JSON Schema.

Des informations complètes sur la spécification OpenAPI (OAS) sont disponibles pour un accès immédiat ici: https://spec.openapis.org/oas/v3.1.0 Il comprend des définitions, des spécifications, y compris des objets de schéma, et bien plus encore.

En outre, l’OAI a parrainé la création d’une nouvelle documentation pour faciliter la compréhension de la structure de la spécification et de ses avantages. Il est disponible ici: https://oai.github.io/Documentation. Il est destiné aux concepteurs et aux rédacteurs d’API basés sur HTTP qui souhaitent bénéficier de la formalisation de leur API dans un document de description OpenAPI.

Qu’est-ce que la spécification OpenAPI?

L’OEA est la norme de l’industrie pour décrire les API modernes. Il définit une description d’interface standard et indépendante du langage de programmation pour les API HTTP, qui permet aux humains et aux ordinateurs de découvrir et de comprendre les capacités d’un service sans avoir besoin d’accéder au code source, à une documentation supplémentaire ou à l’inspection du trafic réseau.

L’OEA est utilisé par des organisations du monde entier, notamment Atlassian, Bloomberg, eBay, Google, IBM, Microsoft, Oracle, Postman, SAP, SmartBear, Vonage et bien d’autres.

Schéma JSON désormais pris en charge

L’objet de schéma définit tout ce qui se trouve à l’intérieur du mot-clé `schema` dans OpenAPI. Auparavant, cela était vaguement basé sur le schéma JSON et appelé «sur-ensemble de sous-ensemble» car il ajoutait certains éléments et supprimait d’autres éléments du schéma JSON. Les communautés OpenAPI et JSON Schema ont travaillé ensemble pour aligner les spécifications afin d’aligner les outils et l’approche.

La prise en charge du schéma JSON moderne est un pas en avant significatif.

«Le décalage entre les structures de type schéma OpenAPI JSON et le schéma JSON lui-même a longtemps été un problème pour les utilisateurs et les implémenteurs. L’alignement complet d’OpenAPI 3.1.0 avec le projet JSON Schema 2020-12 permettra non seulement d’économiser beaucoup de peine aux utilisateurs, mais aussi d’inaugurer une nouvelle approche normalisée des extensions de schéma », a déclaré Ben Hutton, responsable du projet JSON Schema.

«Nous avons passé les dernières années (et la sortie) à nous assurer que nous pouvons clairement entendre et comprendre les problèmes auxquels la communauté est confrontée. Grâce à notre effort de bénévolat limité dans le temps, non seulement nous avons corrigé de nombreux problèmes et ajouté de nouvelles fonctionnalités, mais les vocabulaires de schéma JSON permettent de définir des normes qui répondent aux cas d’utilisation au-delà de la validation, tels que la génération de code, l’interface utilisateur, et la documentation. »

Changements majeurs dans la spécification OpenAPI 3.1.0

• Alignement des vocabulaires de schéma JSON
• Nouvel élément de niveau supérieur pour décrire les Webhooks enregistrés et gérés hors bande
• Prise en charge de l’identification des licences API à l’aide de l’identifiant SPDX standard
• L’objet PathItems est désormais facultatif pour simplifier la création de bibliothèques de composants réutilisables. Les PathItems réutilisables peuvent être décrits dans l’objet composants. Il existe également une prise en charge de la description des API sécurisées à l’aide de certificats clients.

Les détails complets de l’OAS 3.1.0 sont disponibles ici: https://spec.openapis.org/oas/v3.1.0 La nouvelle documentation est disponible ici: https://oai.github.io/Documentation/

Impliquez-vous dans l’OAI

Pour en savoir plus sur la participation à l’évolution de l’OEA: https://www.openapis.org/participate/how-to-contribute

Conclusion

Afin d’atteindre l’objectif impressionnant de compatibilité totale avec le schéma JSON moderne, l’OAS a subi d’importantes mises à jour qui facilitent beaucoup les choses pour les responsables de la maintenance des outils, car ils n’ont plus besoin d’essayer de deviner le brouillon d’un schéma en regardant où il se trouve. référencé à partir de. C’est précisément ce qui rend la mise en œuvre d’OEA 3.1.0 importante à évaluer et à prendre en compte.