Emmanuel SAUVAGE

10 min de lecture

OpenAPI comme contrat d’API : aligner back, front et QA

Spécification partagée, génération de clients, mocks et tests de non-régression sur le schéma — sans bloquer la livraison.

  • OpenAPI
  • API
  • Qualité
Schéma : contrat OpenAPI partagé entre équipes Contrat → clients → tests openapi.yaml → SDK / mocks → Tests contrat

Ce que le contrat doit figer

  • Chemins, méthodes, codes de réponse et schémas JSON (requête / réponse).
  • Authentification (Bearer, clé API, cookies) et en-têtes obligatoires.
  • Règles de pagination, filtres et formats d’erreur (ex. Problem Details).

Workflow réaliste

Design first : on écrit ou met à jour la spec avant d’implémenter le endpoint critique. Code first : on génère la spec depuis les attributs PHP — utile si l’équipe tient la discipline des annotations. L’essentiel est une source de vérité unique référencée en revue de code.

Clients et mocks

À partir d’OpenAPI 3, on peut générer des clients TypeScript ou des stubs serveur pour les tests d’intégration. Les mocks permettent au front d’avancer pendant que le back finalise — à condition que le contrat soit validé (PR sur le YAML/YML ou JSON).

Casser le contrat sans surprise

  • Versionner l’API (URL /v2 ou négociation documentée).
  • Marquer les champs dépréciés dans la spec avant retrait.
  • Ajouter des tests de non-régression sur le schéma (diff OpenAPI en CI ou contrats consumer-driven).

FAQ

OpenAPI remplace-t-il les tests fonctionnels ?

Non : il garantit la forme des échanges, pas la logique métier. Il complète les tests E2E et les scénarios métier.

Spec trop grosse à maintenir ?

Découpez par domaine (paths/orders.yaml + components/schemas) et assemblez avec des outils de merge ; ou limitez la spec publique aux surfaces externes et gardez l’interne documentée autrement.