Spécification OpenAPI - OpenAPI Specification

La spécification OpenAPI , anciennement connue sous le nom de spécification Swagger , est une spécification pour les fichiers d' interface lisibles par machine pour décrire, produire, consommer et visualiser des services Web RESTful . Auparavant intégré au framework Swagger , il est devenu un projet distinct en 2016, supervisé par l'OpenAPI Initiative, un projet de collaboration open source de la Linux Foundation . Swagger et certains autres outils peuvent générer du code, de la documentation et des cas de test à partir d'un fichier d'interface.

Histoire

Le développement de Swagger a commencé début 2010 par Tony Tam, qui travaillait pour la société de dictionnaires en ligne Wordnik . Après une rencontre avec Kin Lane (Comité de pilotage OpenAPI) et Tony Tam le 12 juin 2014, Kin Lane a approché Owen Rubel qui travaillait sur une approche similaire et lui a emprunté ses idées pour la nouvelle spécification Swagger 2.0 (qui deviendrait finalement OpenAPI) .

En mars 2015, SmartBear Software a acquis la spécification d'API Swagger open source de Reverb Technologies, la société mère de Wordnik.

En novembre 2015, SmartBear a annoncé la création d'une nouvelle organisation appelée OpenAPI Initiative sous le parrainage de la Linux Foundation . Parmi les autres sociétés membres fondatrices figuraient 3scale , Apigee , Capital One , Google , IBM , Intuit , Microsoft , PayPal et Restlet. SmartBear a fait don de la spécification Swagger au nouveau groupe. RAML et API Blueprint étaient également à l'étude par le groupe.

Le 1er janvier 2016, la spécification Swagger a été renommée OpenAPI Specification (OAS) et a été déplacée vers un nouveau référentiel GitHub .

En septembre 2016, la conférence API World a décerné un prix API Infrastructure à SmartBear pour ses travaux en cours sur Swagger.

En juillet 2017, l'OpenAPI Initiative a publié la version 3.0.0 de sa spécification. MuleSoft , le principal contributeur au langage de modélisation d'API RESTful alternatif (RAML), a rejoint l'OAS et a ouvert son outil API Modeling Framework, qui peut générer des documents OAS à partir d'entrées RAML.

En février 2021, l'OpenAPI Initiative a publié la version 3.1.0. Les principaux changements dans la spécification OpenAPI 3.1.0 incluent l'alignement des vocabulaires du schéma JSON, un nouvel élément de niveau supérieur pour décrire les Webhooks enregistrés et gérés hors bande, la prise en charge de l'identification des licences API à l'aide de l'identifiant SPDX standard et l'objet PathItems est désormais facultatif à faire il est plus simple de créer des bibliothèques de composants réutilisables.

Date de sortie

Version Date Remarques
3.1.0 2021-02-15 Publication de la spécification OpenAPI 3.1.0
3.0.3 2020-02-20 Version de correctif de la spécification OpenAPI 3.0.3
3.0.2 2018-10-08 Version de correctif de la spécification OpenAPI 3.0.2
3.0.1 2017-12-06 Version de correctif de la spécification OpenAPI 3.0.1
3.0.0 2017-07-26 Publication de la spécification OpenAPI 3.0.0
2.0 2014-09-08 Sortie de Swagger 2.0
1.2 2014-03-14 Publication initiale du document formel
1.1 2012-08-22 Sortie de Swagger 1.1
1,0 2011-08-10 Première version de la spécification Swagger

Usage

Les applications implémentées sur la base de fichiers d'interface OpenAPI peuvent générer automatiquement une documentation des méthodes, des paramètres et des modèles. Cela permet de garder la documentation , les bibliothèques clientes et le code source synchronisés.

Caractéristiques

La spécification OpenAPI est indépendante du langage. Avec la spécification de ressources déclarative d'OpenAPI , les clients peuvent comprendre et consommer des services sans connaître l'implémentation du serveur ou accéder au code du serveur.

Outils qui fonctionnent avec OpenAPI

L'OpenAPI Initiative maintient une liste d'implémentations pour la version 3.0 de la spécification. SmartBear marque toujours ses outils OpenAPI avec le surnom de Swagger. Le framework d'interface utilisateur Swagger permet aux développeurs et aux non-développeurs d'interagir avec l'API dans une interface utilisateur sandbox qui donne un aperçu de la façon dont l'API répond aux paramètres et aux options. Swagger peut gérer à la fois JSON et XML .

Swagger Codegen contient un moteur basé sur des modèles pour générer de la documentation, des clients API et des stubs de serveur dans différentes langues en analysant la définition OpenAPI. En Juillet 2018, William Cheng, le premier contributeur à Swagger Codegen, et plus de 40 autres contributeurs à Swagger Codegen fourchue le code dans un projet nommé OpenAPI générateur dans l'organisation Outils OpenAPI.

Conférence annuelle

L'OpenAPI Initiative parraine chaque année une API Specifications Conference (ASC). L'événement trouve son origine dans l'API Strategy and Practice Conference (APIStrat) qui s'est déroulée pendant de nombreuses années et est devenue partie intégrante de l'OpenAPI Initiative en 2016.

Voir également

Les références

Bibliographie

  • Haupt, F.; Karastoyanova, D.; Leymann, F.; Schroth, B. (2014). Une approche axée sur les modèles pour les services conformes à REST . ICWS 2014. Conférence internationale IEEE 2014 sur les services Web . p. 129-136. doi : 10.1109/ICWS.2014.30 . ISBN 978-1-4799-5054-6.
  • Pautasso, César (2021). Belles API . LeanPub. p. 100.

Liens externes