openapi-typescript pour TypeScript : guide complet avec exemples

Dans le développement web moderne, les API jouent un rôle crucial, et leur spécification via le standard OpenAPI (anciennement Swagger) est devenue la norme de facto. Cependant, maintenir manuellement les types TypeScript en adéquation avec une spécification OpenAPI est un processus fastidieux et sujet aux erreurs. La bibliothèque openapi-typescript résout ce problème en générant automatiquement des types TypeScript stricts à partir de votre schéma OpenAPI (v3.0 et v3.1).

L'objectif principal de la bibliothèque est d'assurer une interaction type-safe avec l'API. Au lieu de déclarer manuellement des interfaces pour chaque endpoint, vous exécutez un générateur qui crée un fichier unique (ou plusieurs) contenant les types pour toutes les requêtes, réponses, paramètres et schémas. Cela permet non seulement de gagner du temps, mais aussi de garantir que vos types sont toujours synchronisés avec la version actuelle de l'API. Si la spécification change, il suffit de régénérer les types, et le compilateur TypeScript signalera immédiatement toutes les incohérences dans le code.

La bibliothèque est largement utilisée dans les projets où la fiabilité et la rapidité de développement sont essentielles : des architectures de microservices aux applications SPA. Elle prend en charge la génération de types pour le côté client (par exemple, pour fetch ou axios) ainsi que pour le côté serveur (par exemple, pour Express ou Fastify). Dans cet article, nous allons détailler l'installation, les méthodes principales, des exemples concrets et les erreurs courantes.

Installation

Pour installer la bibliothèque, utilisez npm ou yarn. La commande installe à la fois le générateur et les dépendances nécessaires.

npm install openapi-typescript typescript @types/node --save-dev

Ou via yarn :

yarn add -D openapi-typescript typescript @types/node

Si vous prévoyez d'utiliser les types générés à l'exécution (par exemple, pour la validation), installez également openapi-typescript-helpers :

npm install openapi-typescript-helpers

Démarrage rapide — exemple minimal fonctionnel

Supposons que vous ayez un fichier spec.yaml contenant une spécification OpenAPI. Créons un script simple pour générer les types.

// generate.ts
import { createClient } from 'openapi-typescript';
import * as fs from 'fs';

async function main() {
  const spec = fs.readFileSync('./spec.yaml', 'utf-8');
  const result = await createClient(spec, { format: 'yaml' });
  fs.writeFileSync('./api-types.d.ts', result);
  console.log('Types générés dans api-types.d.ts');
}

main().catch(console.error);

Exécutez le script :

npx ts-node generate.ts

Après cela, le fichier api-types.d.ts contiendra tous les types correspondant à votre spécification. Vous pouvez maintenant les importer dans votre projet :

import type { paths, components } from './api-types';

// Utilisation du type pour un endpoint spécifique
type GetUsersResponse = paths['/users']['get']['responses'][200]['content']['application/json'];

Méthodes et fonctions principales

1. createClient(schema: string, options?: ClientOptions): Promise<string>

Fonctionnement : Méthode principale pour générer les types. Elle prend une chaîne contenant la spécification (JSON ou YAML) et retourne une chaîne avec le code TypeScript.

import { createClient } from 'openapi-typescript';
import * as fs from 'fs';

const spec = fs.readFileSync('./spec.json', 'utf-8');
const types = await createClient(spec, { format: 'json' });
fs.writeFileSync('./types.d.ts', types);

2. createClientFromUrl(url: string, options?: ClientOptions): Promise<string>

Fonctionnement : Charge de manière asynchrone la spécification depuis une URL et génère les types. Utile pour les API distantes.

                
    

  
Aussi dans la bibliothèque
  

                
                  
                 ts-jest pour TypeScript : guide complet avec exemples
      
                
                  
                 Travailler avec les dates en TypeScript : aperçu des bibliothèques date-fns, Luxon et Day.js
      
                
                  
                 Files d'attente de tâches pour Swift : guide complet sur GCD et Operation Queues
      
                
                  
                 ORM pour Kotlin : comparaison et exemples (Exposed, Ktorm, Hibernate)
      
                
                  
                 Boost pour C++ : guide complet avec exemples