OpenAPI
| Développé par | Initiative OpenAPI (d) et Fondation Linux |
|---|---|
| Dernière version | 3.1.1 ()[1] |
| Dépôt | github.com/OAI/OpenAPI-Specification |
| Type |
Spécification Interface description language |
| Licence | Licence Apache 2.0 |
| Site web | openapis.org |
OpenAPI, connu dans ces 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[2].
Historique
[modifier | modifier le code]Le développement de Swagger a débuté en 2010, par Tony Tam, qui travaillait pour l'entreprise Wordnik[3].
En mars 2015 la société SmartBear a acquis la spécification open-source Swagger, de Reverb Technologies, maison mère de Wordnik[4].
En novembre 2015 SmartBear a annoncé donner la spécification Swagger à une nouvelle organisation appellée OpenAPI Initiative, sous le parrainage de la Fondation Linux[5].
En juillet 2017 OpenAPI Initiative a sorti la version 3.0.0 de la spécification[6], puis, en février 2021, la version 3.1.0[7].
Historique des versions[8]
[modifier | modifier le code]| Version | Date | Notes |
|---|---|---|
| 3.1.1 | 24 octobre 2024 | |
| 3.1.0 | 16 février 2021 | |
| 3.0.4 | 24 octobre 2024 | |
| 3.0.3 | 21 février 2020 | |
| 3.0.2 | 8 octobre 2018 | |
| 3.0.1 | 7 décembre 2017 | |
| 3.0.0 | 26 juillet 2017 | Première version de OpenAPI |
Exemple
[modifier | modifier le code]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 openAPI[9]
openapi: 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
[modifier | modifier le code]Une spécification au format OpenAPI peut être utilisée par de nombreuses applications et outils[10]. Il est par exemple possible de générer un échafaudage pour le serveur, des clients[11], de la documentation ou de valider qu'une requête ou une réponse est conforme à la spécification OpenAPI[12].
Pratiques d'ingénierie logicielle[13]
[modifier | modifier le code]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
[modifier | modifier le code]- ↑ « Release 3.1.1 », (consulté le )
- ↑ (en) « What is OpenAPI? » (consulté le )
- ↑ (en) « Swagger creator joins SmartBear » (consulté le )
- ↑ (en) « SmartBear Acquires Swagger » (consulté le )
- ↑ (en) « OpenAPI - FAQ » (consulté le )
- ↑ (en) « The OAI Announces the OpenAPI Specification 3.0.0 » (consulté le )
- ↑ (en) « OpenAPI Specification 3.1.0 Available Now » (consulté le )
- ↑ (en) « OpenAPI Specification - Releases » (consulté le )
- ↑ (en) « Open API Map » (consulté le )
- ↑ (en) « OpenAPI.Tools » (consulté le )
- ↑ (en) « OpenAPI Generator » (consulté le )
- ↑ (en) « Express OpenApi Validator » (consulté le )
- ↑ (en) McKenzie Tucci, « Code-First vs. Design-First: Eliminate Friction with API Exploration » (consulté le )
