Génération Swagger/OpenAPI pour TypeScript : bibliothèques et outils

Génération Swagger/OpenAPI pour TypeScript : automatisation de la création de clients API

\n

Lors du développement d'applications web modernes en TypeScript, on rencontre souvent le besoin d'intégrer une API REST décrite via des spécifications OpenAPI (anciennement connues sous le nom de Swagger). L'écriture manuelle des types, des interfaces et du code client prend non seulement beaucoup de temps, mais est également source d'erreurs, surtout lors de modifications du backend. Des outils de génération automatique de code TypeScript à partir de spécifications OpenAPI viennent à la rescousse. Dans cet article, nous examinerons trois solutions les plus populaires : openapi-typescript, orval et swagger-typescript-api, et comparerons leurs fonctionnalités.

\n\n

Pourquoi générer du TypeScript à partir d'OpenAPI ?

\n

L'objectif principal est la synchronisation des types et du code client entre le frontend et le backend. Avantages de la génération automatique :

\n

\n
• Sécurité des types : Tous les endpoints, paramètres de requête et réponses reçoivent des types TypeScript stricts.
\n
• Actualité : Lorsque la spécification change, il suffit de régénérer le code, sans modifications manuelles.
\n
• Accélération du développement : Le développeur obtient des fonctions prêtes à l'emploi pour appeler l'API avec l'auto-complétion (IntelliSense).
\n
• Minimisation des erreurs : Les fautes de frappe dans les noms de champs et les incohérences de types sont éliminées.
\n

\n\n

openapi-typescript

\n

La bibliothèque openapi-typescript (des créateurs de openapi-fetch) est un générateur de types léger. Elle crée uniquement des interfaces et des types TypeScript, sans générer de code client pour les appels API. C'est un choix idéal pour les projets où l'on souhaite typer strictement les données, mais où la méthode d'appel API reste à la discrétion du développeur (par exemple, via fetch ou axios).

\n

Installation :

\n

npm install -D openapi-typescript

\n

Exemple d'utilisation (génération de types à partir du fichier spec.yaml) :

\n

npx openapi-typescript ./spec.yaml -o ./types/api.ts

\n

Le résultat est un fichier avec des types qui peuvent être importés :

\n

import type { paths } from './types/api';\n\n// Type pour la réponse de GET /users\ntype UsersResponse = paths['/users']['get']['responses'][200]['content']['application/json'];

\n

Avantages : Minimalisme, génération rapide, excellente prise en charge des schémas complexes (allOf, oneOf).
\nInconvénients : Pas de fonctions prêtes à l'emploi pour appeler l'API, nécessite une couche d'abstraction supplémentaire.

\n\n

orval

\n

Orval est un générateur puissant qui crée non seulement des types, mais aussi des hooks React entièrement fonctionnels, ainsi que des clients pour axios, fetch ou Angular. Il est particulièrement utile dans les projets React utilisant React Query (TanStack Query).

\n

Installation :

\n

npm install -D orval

\n

Configuration dans le fichier orval.config.ts :

\n

export default {\n  petstore: {\n    input: './swagger.yaml',\n    output: {\n      target: './src/generated',\n      client: 'react-query', // ou 'axios', 'fetch', 'angular'\n    },\n  },\n};

\n

Lancement de la génération :

\n

npx orval

\n

Exemple de hook généré :

\n

import { useGetUsers } from './src/generated/users';\n\nfunction UsersList() {\n  const { data, isLoading, error } = useGetUsers();\n  // data sera typé automatiquement\n}

\n

Avantages : Intégration prête avec React Query, prise en charge des mutations, gestion automatique du cache.
\nInconvénients : Volume important de code généré, dépendance à un client HTTP spécifique.

\n\n

swagger-typescript-api

\n

La bibliothèque swagger-typescript-api offre une génération flexible : on peut obtenir à la fois des types simples et un client API complet avec prise en charge de différents clients HTTP (axios, fetch). Sa particularité est la possibilité de personnaliser les modèles de génération.

\n

Installation :

\n<