# Faire d'un contrat d'API la source unique de vérité

> Faire d'un contrat d'API la source unique de vérité, et en dériver automatiquement clients, types et validations plutôt que de les recopier à la main, est une pratique que j'applique dès qu'un projet comporte une API bien définie.

- Source canonique : [https://allaux.fr/expertises/generation-de-code-depuis-openapi](https://allaux.fr/expertises/generation-de-code-depuis-openapi)
- Langue : FR
- Dernière mise à jour : 2026-07-26

## Le besoin type

Sur un projet avec une API consommée par plusieurs consommateurs — un frontend, une application mobile, un partenaire externe — la description du contrat d'échange se retrouve souvent recopiée à plusieurs endroits : dans le code backend, dans le code frontend, dans une documentation à part. Ces copies divergent presque inévitablement dans le temps, un champ renommé côté backend sans que le frontend ne soit mis à jour en même temps, une documentation qui devient fausse sans que personne ne s'en aperçoive.

## Comment j'interviens sur ce genre de besoin

La spécification OpenAPI décrit précisément les routes, les paramètres, les formats de requête et de réponse d'une API, dans un format structuré et lisible par des outils. Plutôt que de l'écrire après coup à titre documentaire, je la traite comme la source de vérité du projet : le code backend peut être généré ou validé à partir d'elle, et surtout le code client (types, fonctions d'appel, validations) est généré automatiquement pour chaque consommateur, sans recopie manuelle.

Cette approche déplace une catégorie d'erreurs du moment de l'exécution en production vers le moment de la compilation ou de la génération : un champ renommé dans la spécification casse immédiatement la génération du code client, avec une erreur explicite et localisée, plutôt qu'un bug découvert par un utilisateur des semaines plus tard. La mise en place initiale demande une discipline de mise à jour de la spécification à chaque changement d'API, ce qui est un changement d'habitude plus qu'une difficulté technique.

## Facteurs qui influencent le chiffrage

- **API existante ou à concevoir** — Documenter une API déjà en place demande un travail de reconstitution différent de la conception d'une spécification dès la création de l'API.
- **Nombre de consommateurs de l'API** — Le bénéfice de la génération automatique croît avec le nombre de clients différents à maintenir synchronisés avec le contrat.
- **Complexité des types de données** — Des structures de données imbriquées ou avec de nombreux cas de validation demandent une spécification plus détaillée à écrire et à maintenir.
- **Intégration à la chaîne de développement** — Automatiser la génération à chaque changement de spécification, plutôt qu'une génération manuelle occasionnelle, demande une mise en place initiale supplémentaire dans l'outillage du projet.

## Questions à se poser avant de lancer

> Combien de consommateurs différents utilisent ou utiliseront cette API ? Existe-t-il déjà une documentation informelle à formaliser, ou tout est-il à concevoir depuis le début ? Qui sera responsable de maintenir la spécification à jour dans la durée ?

## FAQ

### Cette approche s'applique-t-elle à une API déjà en production ?

Oui, il est possible de documenter une API existante a posteriori sous forme de spécification OpenAPI, puis de basculer progressivement vers une génération de code à partir de cette spécification.

### Faut-il changer de langage ou de framework pour adopter cette pratique ?

Non, des outils de génération existent pour la plupart des langages et frameworks courants ; l'adoption se fait sans remettre en cause la stack technique déjà en place.

### Que se passe-t-il si la spécification n'est pas tenue à jour ?

Le bénéfice disparaît progressivement, d'où l'intérêt d'intégrer la génération dans la chaîne de développement habituelle, pour que la mise à jour devienne une étape naturelle plutôt qu'une tâche facilement oubliée.