OpenAPI

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

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

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

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.

• Portail de la programmation informatique