Génération Swagger/OpenAPI pour TypeScript : les meilleurs outils

Génération Swagger/OpenAPI pour TypeScript : Guide complet des outils

\n\n

Le développement d'applications web modernes en TypeScript est indissociable de la création de clients API typés. Écrire manuellement des interfaces pour chaque endpoint est une tâche laborieuse et sujette aux erreurs. Heureusement, il existe une approche puissante : la génération automatique de code TypeScript à partir de spécifications OpenAPI (Swagger). Dans cet article, nous allons détailler les meilleurs outils pour cette tâche, leurs fonctionnalités et des exemples d'utilisation.

\n\n

Pourquoi utiliser la génération à partir d'OpenAPI ?

\n

OpenAPI (anciennement Swagger) est un standard de description d'API REST. En utilisant un fichier de spécification YAML ou JSON, vous obtenez :

\n

\n
• Typage à 100% — des interfaces TypeScript correspondant exactement au schéma des requêtes et réponses
\n
• Synchronisation avec le backend — lors d'un changement d'API, il suffit de régénérer le code
\n
• Réduction des erreurs — le compilateur TypeScript détecte les incohérences de types dès la phase de développement
\n
• Saisie automatique dans l'IDE — IntelliSense suggère les champs et les types
\n

\n\n

Top des outils de génération TypeScript à partir d'OpenAPI

\n\n

1. openapi-typescript-codegen (recommandé)

\n

Cet outil a gagné en popularité grâce à sa simplicité et son approche moderne. Il génère un code propre et bien structuré avec le support d'axios ou fetch.

\n\n

Installation :

\n

npm install -D openapi-typescript-codegen

\n\n

Exemple d'utilisation :

\n

npx openapi-typescript-codegen --input ./spec.yaml --output ./generated --client axios

\n\n

Code généré :

\n

// generated/models/User.ts\nexport interface User {\n    id: number;\n    name: string;\n    email: string;\n    role: 'admin' | 'user';\n}\n\n// generated/services/UserService.ts\nexport class UserService {\n    public async getUsers(): Promise<User[]> {\n        return this.httpRequest.request({\n            method: 'GET',\n            url: '/users',\n        });\n    }\n}

\n\n

Avantages :

\n

\n
• Support d'OpenAPI 3.0 et 3.1
\n
• Génération de modèles, services et types pour les requêtes
\n
• Génération optionnelle de hooks pour React Query
\n
• Modèles personnalisables via Handlebars
\n

\n\n

2. OpenAPI Generator (openapi-generator)

\n

Générateur officiel de la communauté OpenAPI. Prend en charge plus de 50 langues, dont TypeScript (plusieurs générateurs).

\n\n

Installation :

\n

npm install -D @openapitools/openapi-generator-cli

\n\n

Exemple d'utilisation :

\n

npx openapi-generator-cli generate \\\n    -i spec.yaml \\\n    -g typescript-axios \\\n    -o ./generated

\n\n

Code généré :

\n

// generated/api.ts\nexport const UsersApiAxiosParamCreator = {\n    getUsers: async (options?: AxiosRequestConfig): Promise<RequestArgs> => {\n        const localVarPath = `/users`;\n        return {\n            url: localVarPath,\n            method: 'GET',\n        };\n    }\n}

\n\n

Caractéristiques :

\n

\n
• Générateurs : typescript-axios, typescript-fetch, typescript-angular
\n
• Support de l'authentification (OAuth2, API Key)
\n
• Génération de documentation et de tests
\n
• Fonctionne via CLI ou plugins Maven/Gradle
\n

\n\n

3. swagger-typescript-api

\n

Générateur léger et rapide, axé sur un TypeScript propre sans dépendances superflues.

\n\n

Installation :

\n

npm install -D swagger-typescript-api

\n\n

Exemple d'utilisation :

\n

npx swagger-typescript-api -p ./spec.yaml -o ./generated -n api.ts

\n\n

Code généré :