OpenAPI

Qu’est-ce qu’OpenAPI ?

OpenAPI est une description lisible par machine d’une API HTTP. Rédigé en YAML ou JSON, un document unique répertorie chaque endpoint, ses paramètres, les corps de requête, les réponses et l’authentification. Comme il est structuré, divers outils peuvent l’exploiter : des interfaces de documentation, des clients typés, des stubs de serveur, des mocks et des validateurs.

Swagger était le nom d’origine ; aujourd’hui, ce terme désigne l’outillage, et plus particulièrement Swagger UI. La spécification elle-même est OpenAPI, et elle est devenue le standard de facto pour décrire les API REST. Si vous avez déjà utilisé une référence d’API interactive avec un bouton « Try it out », vous avez utilisé OpenAPI.

La structure d’un document

Un document OpenAPI comporte quelques sections de premier niveau.

# openapi.yaml
openapi: 3.1.0
info:
  title: Posts API
  version: 1.0.0
servers:
  - url: https://api.example.com/v1
paths:
  /posts:
    get:
      summary: List posts
      responses:
        "200":
          description: A list of posts

• openapi déclare la version de la spécification.
• info contient le titre, la version et la description.
• servers liste les URLs de base.
• paths décrit chaque endpoint et ses opérations.
• components contient les éléments réutilisables.

Chemins et opérations

Chaque chemin est associé à une ou plusieurs méthodes HTTP, et chaque opération décrit ses entrées et sorties.

# paths.yaml
paths:
  /posts/{id}:
    get:
      summary: Get a post
      parameters:
        - name: id
          in: path
          required: true
          schema: { type: string }
      responses:
        "200":
          description: The post
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Post"
        "404":
          description: Not found

Les paramètres peuvent se trouver dans le path, le query, le header ou le cookie. Les corps de requête sont déclarés avec un type de contenu et un schéma, et chaque réponse doit lister ses codes de statut et ses structures. De bons résumés et des descriptions précises transforment la spécification en une documentation utile à elle seule.

Composants et références

La réutilisation est la clé du maintien d’une spécification. Définissez vos structures une seule fois et référencez-les avec $ref.

# components.yaml
components:
  schemas:
    Post:
      type: object
      required: [id, title]
      properties:
        id: { type: string }
        title: { type: string }
        publishedAt: { type: string, format: date-time }
  parameters:
    Limit:
      name: limit
      in: query
      schema: { type: integer, minimum: 1, maximum: 100 }
  responses:
    NotFound:
      description: Resource not found

Toute modification apportée au schéma Post met à jour chaque opération qui y fait référence, ce qui évite la désynchronisation courante lors de la duplication des définitions.

Sécurité

L’authentification est déclarée une seule fois et appliquée par opération.

# security.yaml
components:
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT

security:
  - bearerAuth: []

Les outils peuvent ensuite envoyer les bons identifiants dans l’interface utilisateur de la documentation, et les clients générés peuvent accepter un paramètre de token.

Documentation et génération de code

La spécification pilote l’outillage :

• Swagger UI génère une référence interactive où les utilisateurs peuvent tester les requêtes.
• Redoc génère une page de documentation épurée à trois colonnes.
• openapi-generator produit des clients et des stubs de serveur dans de nombreux langages.
• openapi-typescript génère des types TypeScript à partir de la spécification.
• Spectral analyse la spécification (linting) pour en vérifier la cohérence et le style.
• Les serveurs de mock fournissent des réponses d’exemple afin que le travail sur le front-end puisse commencer avant que le backend ne soit prêt.

# docs.sh
npx @redocly/cli preview-docs openapi.yaml
npx openapi-typescript openapi.yaml -o src/api-types.ts

Comme tout dérive d’un seul fichier, la documentation, les clients et les types restent cohérents.

Spec-first versus code-first

Il existe deux flux de travail :

• Spec-first : concevoir le contrat avant l’implémentation. Idéal pour les API publiques, les multiples consommateurs et le travail parallèle entre le front-end et le back-end. La spec est la source de vérité.
• Code-first : annoter les routes et les types, puis générer la spec. Cela permet de garder la spec proche de l’implémentation et d’éviter la duplication dans les frameworks typés.

Les deux approches fonctionnent. Le risque majeur, dans les deux cas, est de maintenir la documentation manuellement dans un endroit séparé, où elle devient obsolète sans que l’on s’en aperçoive.

Validation et tests de contrat

Un document OpenAPI peut être appliqué, et pas seulement consulté.

• Validation des requêtes : le middleware rejette les requêtes qui ne correspondent pas à la spécification, permettant ainsi aux handlers de faire confiance à leurs entrées.
• Validation des réponses : les tests vérifient que les réponses correspondent aux schémas déclarés.
• Tests de contrat : les clients et les serveurs s’appuient sur la même spécification, permettant de détecter rapidement les changements incompatibles (breaking changes).

C’est là que la spécification prend tout son sens : elle devient un contrat exécutable plutôt qu’une simple décoration.

Bonnes pratiques

• Maintenez une seule spécification par API et considérez-la comme la source de vérité.
• Réutilisez les schémas, paramètres et réponses avec $ref.
• Rédigez des résumés et des descriptions clairs ; ils constitueront votre documentation.
• Documentez chaque code de statut qu’une opération peut retourner.
• Validez les requêtes et les réponses par rapport à la spécification.
• Générez les clients, les types et la documentation plutôt que de les écrire à la main.
• Passez la spécification au lint et examinez les modifications dans les pull requests.

Erreurs courantes

• Maintenir la documentation manuellement et séparément de la spec.
• Dupliquer les schémas en ligne jusqu’à ce qu’ils divergent.
• Oublier les réponses d’erreur, empêchant ainsi les clients de gérer les échecs.
• Utiliser des noms et des descriptions vagues qui n’aident pas les consommateurs.
• Laisser la spec s’écarter de l’implémentation.
• Sauter l’étape de validation et perdre ainsi le principal avantage du contrat.

Et après ?

OpenAPI transforme une API en un contrat utilisable aussi bien par des outils que par des humains. Construisez-la sur des bases solides de conception REST, faites-la évoluer avec prudence via le versionnage d’API et alignez-la sur le guide HTTP. Ensuite, décrivez l’un de vos endpoints existants et générez un client à partir de celui-ci.