02 • 34 • 09 • 31 • 70
Dans le développement d’applications modernes, la communication entre le front-end et l’API est parfois un maillon faible. Trop souvent, le “contrat” qui lie ces deux mondes est informel : une documentation Swagger que l’on consulte du coin de l’œil tout en réécrivant manuellement des interfaces TypeScript. Cette double saisie est une source majeure de bugs : une simple modification du schéma d'API par le back-end peut briser le front-end sans que celui-ci donne l'alerte.
Et si votre documentation OpenAPI (Swagger) n'était plus un simple document de consultation, mais la source de vérité unique injectée directement dans votre code ? C'est ce que permet openapi-fetch.
Pourquoi openapi-fetch change la donne ?
L'approche traditionnelle consiste soit à typer manuellement ses retours d'API avec des “as MyInterface”, avec des bibliothèques comme Axios ou alors le fetch natif.
Openapi-fetch propose une nouvelle voie : celle du "Type-Only".
- La fin du typage manuel : Plus besoin de copier-coller des interfaces depuis une doc. Si l'API définit un champ “user_id”, votre front-end le sait instantanément.
- Une couche ultra-fine : Contrairement à Axios ou aux clients générés massivement, openapi-fetch pèse moins de 1 Ko. Il ne remplace pas fetch, il l'habille intelligemment avec les types générés de votre schéma.
- Sécurité à la compilation : Le gain principal est la détection des erreurs en amont. Si une route change ou qu'un paramètre devient obligatoire dans Swagger, votre projet ne compilera plus tant que vous n'aurez pas corrigé l'appel correspondant.
Les bases du fonctionnement
La puissance d'openapi-fetch réside dans sa capacité à transformer un fichier YAML ou JSON en un moteur de validation. La première étape consiste à extraire les informations de votre API via l'outil openapi-typescript. Cette commande parcourt l'intégralité de votre spécification pour générer des types statiques complexes, incluant les énumérations, les formats de dates et les structures imbriquées.
Une fois ce fichier généré, vous n'avez plus besoin de déclarer d'interfaces manuelles pour vos données d'API. L'instanciation du client devient alors le point d'entrée unique de votre communication. Contrairement à une configuration classique où l'on doit souvent gérer des instances multiples et des types génériques complexes, ici, le client "connaît" déjà toute votre API.
Le véritable gain en qualité se situe dans la gestion des erreurs. Openapi-fetch ne rejette pas de promesse de manière imprévisible (évitant ainsi les blocs try/catch à répétition). Il renvoie un objet structuré { data, error }. Si l'API renvoie une erreur 400 ou 500, le champ error est automatiquement typé selon ce qui a été défini dans le Swagger (par exemple, un objet contenant une liste de champs invalides). Cette approche rend le code beaucoup plus prévisible et facile à tester.
Exemple avancé : L'alliance avec TanStack Query
Si openapi-fetch excelle dans le transport de la donnée, TanStack Query (anciennement React Query) est le standard pour la gestion d'état asynchrone. Dans une application complexe, envoyer une requête ne suffit pas : il faut gérer le cache, les tentatives de reconnexion (retry), les états de chargement, etc.
L'intégration des deux outils crée une synergie parfaite. En utilisant openapi-fetch à l'intérieur d'une “queryFn”, vous bénéficiez d'une inférence complète : de l’API (via le Swagger) jusqu'au composant UI, sans aucune perte d'information.
Cette architecture résout le problème de la “boîte noire” : à tout moment, en survolant une variable dans votre IDE, vous savez exactement si un champ est optionnel, s'il peut être nul, ou quel est le format attendu. Cette clarté réduit drastiquement la charge mentale des développeurs et facilite l'onboarding de nouveaux membres sur un projet. Plus besoin de naviguer entre le code et une page Web Swagger ouverte dans un onglet tiers ; la documentation est “vivante” au sein même de l'éditeur.
Conclusion
L'adoption de openapi-fetch n'est pas seulement un choix technique, c'est un choix méthodologique. Elle force une collaboration saine entre le back-end et le front-end autour d'un contrat d'interface solide.
En éliminant la friction du typage manuel, on gagne en rapidité de développement et, surtout, en sérénité lors des mises en production.
Chez Next Decision, nous maîtrisons l'ensemble de cette chaîne de valeur. Qu'il s'agisse de concevoir des architectures API solides ou d'implémenter des front-ends réactifs et maintenables avec les meilleurs outils de l'écosystème TypeScript (comme TanStack Query et OpenAPI-TS), nous accompagnons nos clients vers des solutions performantes et pérennes.
Nos experts Next Decision sont à votre disposition pour vous accompagner dans la conception d'architectures API solides et dans la mise en place solutions performantes adaptées à vos besoins. Rendez-vous sur la page Contact !
