OpenAPI

Le développement de Swagger a débuté en 2010, par Tony Tam, qui travaillait pour l'entreprise Wordnik^[2].

En mars 2015 la société SmartBear a acquis la spécification open-source Swagger, de Reverb Technologies, maison mère de Wordnik^[3].

En novembre 2015 SmartBear a annoncé donner la spécification Swagger à une nouvelle organisation appelée OpenAPI Initiative, sous le parrainage de la Fondation Linux^[4].

En juillet 2017 OpenAPI Initiative a sorti la version 3.0.0 de la spécification^[5], puis, en février 2021, la version 3.1.0^[6].

Historique des versions#edit

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^[8]

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

Une spécification au format OpenAPI peut être utilisée par de nombreuses applications et outils^[9]. Il est par exemple possible de générer un échafaudage pour le serveur, des clients^[10], de la documentation ou de valider qu'une requête ou une réponse est conforme à la spécification OpenAPI^[11].

Pratiques d'ingénierie logicielle#edit

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")^[12].

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.

1. ^ (en) « What is OpenAPI? » (consulté le 5 avril 2025)
2. ^ (en) « Swagger creator joins SmartBear » (consulté le 6 avril 2025)
3. ^ (en) « SmartBear Acquires Swagger » (consulté le 6 avril 2025)
4. ^ (en) « OpenAPI - FAQ » (consulté le 6 avril 2025)
5. ^ (en) « The OAI Announces the OpenAPI Specification 3.0.0 » (consulté le 6 avril 2025)
6. ^ (en) « OpenAPI Specification 3.1.0 Available Now » (consulté le 6 avril 2025)
7. ^ (en) « OpenAPI Specification - Releases » (consulté le 7 avril 2025)
8. ^ (en) « Open API Map » (consulté le 8 avril 2025)
9. ^ (en) « OpenAPI.Tools » (consulté le 6 avril 2025)
10. ^ (en) « OpenAPI Generator » (consulté le 6 avril 2025)
11. ^ (en) « Express OpenApi Validator » (consulté le 6 avril 2025)
12. ^ (en) McKenzie Tucci, « Code-First vs. Design-First: Eliminate Friction with API Exploration » (consulté le 12 avril 2025)

• Portail de la programmation informatique