OpenAPI, connu dans ses précédentes versions sous le nom de Swagger, est une spécification qui permet de décrire l'API d'un service web sous la forme d'un document YAML ou JSON.
Historique Le développement de Swagger a débuté en 2010, par Tony Tam, qui travaillait pour l'entreprise Wordnik.
En la société SmartBear a acquis la spécification open-source Swagger, de Reverb Technologies, maison mère de Wordnik.
En SmartBear a annoncé donner la spécification Swagger à une nouvelle organisation appelée OpenAPI Initiative, sous le parrainage de la Fondation Linux.
En OpenAPI Initiative a sorti la version 3.0.0 de la spécification, puis, en , la version 3.1.0.
Historique des versions +VersionDateNotes3.2.019 septembre 20253.1.219 septembre 20253.1.124 octobre 20243.1.016 février 20213.0.424 octobre 20243.0.321 février 20203.0.28 octobre 20183.0.17 décembre 20173.0.026 juillet 2017Première version de OpenAPI
Exemple Imaginons un service web ayant un unique point d'accès qui, à une requête GET du type https://example.fr/bonjour-monde?nom=paul retourne la réponse {"message": "bonjour paul"}. Ce service peut être décrit par cette spécification openAPIopenapi: 3.0.3 info: title: Mon Web Service version: 0.0.1 servers: - url: https://example.fr paths: /bonjour-monde: get: summary: Génère un message de salutation parameters: - name: nom in: query schema: type: string responses: "200": description: message de salutation généré content: application/json: schema: type: object properties: message: type: string
Usage Une spécification au format OpenAPI peut être utilisée par de nombreuses applications et outils. Il est par exemple possible de générer un échafaudage pour le serveur, des clients, de la documentation ou de valider qu'une requête ou une réponse est conforme à la spécification OpenAPI.
Pratiques d'ingénierie logicielle Il y a deux workflows principaux pour définir une spécification au format OpenAPI : commencer par implémenter le service web puis utiliser un outil pour générer sa spécification automatiquement à partir de ce code (approche appelée "Code-first") ; ou commencer par écrire la spécification avant de développer le service web (approche appelée "Design-first").
Chacun de ces workflows a ses avantages et inconvénients. Commencer par développer le service web permet de prototyper et d'itérer plus rapidement. Commencer par écrire la spécification permet à toutes les parties prenantes de s'accorder, ce qui peut permettre de travailler en parallèle sur les tâches qui en dépendent (développement du service web, de ses tests et de sa documentation, d'applications qui vont consommer ce service, ...). Cette approche permet aussi d'utiliser un outil capable de générer un échafaudage pour le service à partir de cette spécification, ce qui peut accélérer son développement.
Références
Catégorie:Interface de programmation