OpenAPI

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].

OpenAPI

Informations

Développé par	Initiative OpenAPI (d) et Fondation Linux
Dernière version	3.1.1 (24 octobre 2024)[1]
Dépôt	github.com/OAI/OpenAPI-Specification
Type	Spécification Interface description language
Licence	Licence Apache 2.0
Site web	openapis.org

modifier - modifier le code - voir Wikidata (aide)

Historique

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]

Version	Date	Notes
3.2.0	19 septembre 2025
3.1.2	19 septembre 2025
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

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

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]

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.