Les équipes de développement frontend connaissent bien un cycle répétitif et coûteux. Dès qu’un endpoint d’API est livré, il faut écrire manuellement les fonctions de requête, les types de réponse, les hooks React, les gestionnaires d’état de mutation, les mocks et la logique de validation. Si le backend modifie un seul champ, tout s’effondre : captures d’écran obsolètes, formulaires cassés, interfaces TypeScript mensongères, tickets de QA par dizaines. Plus l’application grossit, plus le problème s’aggrave.
Pourtant, les équipes modernes disposent déjà d’un outil capable de résoudre une grande partie de ce problème : le contrat d’API, généralement défini dans une spécification OpenAPI. Mais beaucoup d’équipes se contentent d’utiliser OpenAPI comme une documentation statique, parfois ignorée. Le véritable levier consiste à traiter OpenAPI comme une source unique de vérité qui alimente toute la couche d’intégration frontend, dans un workflow TypeScript.
L’API d’abord, pas le backend
Nombre d’équipes frontend fonctionnent encore en mode « backend d’abord ». Le cycle classique : conception UI, puis implémentation backend, puis attente du frontend, puis livraison des endpoints, puis intégration frontend, puis découverte des décalages. L’API-First inverse l’ordre : c’est le contrat d’API qui devient le premier livrable. Le frontend peut alors commencer à travailler avant même que le backend existe, non pas avec des mocks artisanaux ou des interfaces devinées, mais avec un contrat réel.
OpenAPI comme actif de développement
Une spécification OpenAPI peut piloter bien plus que Swagger UI. Un workflow moderne peut générer automatiquement des modèles TypeScript, des clients d’API, des hooks React, des utilitaires de requête, des mocks, des schémas de validation, de la documentation et des helpers de test. Le changement conceptuel est essentiel : traiter OpenAPI comme du code source, le versionner, le relire, le différencier, en générer le frontend.
Un dépôt typique peut ainsi contenir un dossier openapi/ avec le schéma YAML, et un outil de génération comme Orval pour produire le code client. En conservant la spécification dans Git, on gagne l’historique des versions, la visibilité pendant les revues, les diff de contrat, l’automatisation CI et la synchronisation d’équipe – les ingénieurs frontend ne dépendent plus de captures d’écran obsolètes de Swagger.
Orval : générer un client typé
Au lieu d’écrire manuellement des wrappers fetch, Orval permet de générer automatiquement les fonctions de requête, les types, les hooks TanStack Query et les helpers de mutation à partir du schéma OpenAPI. Un simple fichier de configuration (orval.config.ts) pointe vers le schéma et définit la sortie. Une commande (pnpm api:generate) suffit pour que tout le code d’intégration soit regénéré.
TanStack Query : la couche de requêtes réelle
Les clients générés deviennent encore plus utiles une fois combinés avec TanStack Query. Après avoir installé la bibliothèque et configuré un QueryClient, les hooks générés (par exemple useGetProducts()) s’utilisent directement, sans hooks écrits à la main, sans logique de chargement dupliquée, sans abstractions fetch copiées-collées.
Zod : la validation à l’exécution
Les interfaces TypeScript générées aident, mais elles ne valident pas les payloads réels. Un serveur peut renvoyer "price": "broken" alors que TypeScript croit qu’il s’agit d’un nombre. C’est là que Zod entre en jeu : en définissant des schémas (par exemple ProductSchema avec z.object({ id: z.number(), title: z.string(), price: z.number() })), la validation à l’exécution détecte immédiatement les erreurs. Les mauvais payloads échouent bruyamment, pas silencieusement.
Commencer le développement frontend avant le backend
L’un des atouts majeurs de ce workflow est la génération de mocks, notamment via MSW (Mock Service Worker). En initialisant un worker dans le navigateur et en créant des handlers qui retournent des données simulées, le frontend peut fonctionner de manière indépendante, même sans backend prêt. Le développement peut ainsi avancer en parallèle, sans attendre.
Un workflow cohérent
En combinant OpenAPI comme contrat central, Orval pour la génération, TanStack Query pour la gestion des requêtes, Zod pour la validation runtime et MSW pour le mocking, les équipes frontend éliminent les répétitions, réduisent les tickets de QA et gagnent en fiabilité. Le contrat d’API devient vraiment le pivot du développement, et non plus une simple documentation.
