JSON vers TypeScript Générer automatiquement des interfaces à partir des réponses API

Vous venez de récupérer des données depuis une API tierce. La réponse est un bloc JSON dense — des objets imbriqués, des tableaux, des champs facultatifs — et vous devez maintenant déterminer comment les typifier en TypeScript. Vous ouvrez un nouveau fichier, commencez à taper interface User { ... }, et 20 minutes plus tard, vous avez quelque chose qui correspond probablement aux données réelles. Probablement.

Il existe une meilleure méthode. Des outils qui convertissent directement le JSON en interfaces TypeScript réduisent cette tâche de 20 minutes à quelques secondes. Cet article explique ce que ressemblent ces types générés, comment gérer les cas complexes (valeurs nulles, unions, nesting profond), et pourquoi il faut associer les types générés à des schémas Zod afin de détecter les incohérences de forme en temps réel — et non seulement en temps de compilation.

Pourquoi les interfaces TypeScript pour les réponses API sont importantes

La valeur de TypeScript réside dans la détection des erreurs avant que le code ne s'exécute. Sans réponses API typées, vous êtes dans l'obscurité : vous accédez à des propriétés qui n'existent peut-être pas, vous traitez des valeurs facultatives comme obligatoires, ou vous convertissez silencieusement une chaîne "null" en quelque chose de différent en aval.

Considérez ce scénario courant :

const user = await fetchUser(id);
console.log(user.address.city); // TypeError at runtime if address is null

Si vous aviez typé la réponse correctement — avec address: Address | null — TypeScript aurait immédiatement signalé cette accès. Le compilateur est votre première ligne de défense, mais seulement si vous lui fournissez quelque chose à travailler.

Écrire manuellement des interfaces pour chaque API est fastidieux et sujet à erreur. Vous mal interprétez le schéma, manquez un champ facultatif, ou copiez-coller une version obsolète. La génération d'interfaces à partir de données JSON réelles élimine cette erreur humaine.

Ce que produit la conversion JSON vers TypeScript

Prenons une réponse API simple :

{
  "id": 42,
  "username": "jsmith",
  "email": "j@example.com",
  "createdAt": "2024-01-15T10:30:00Z",
  "role": "admin",
  "profile": {
    "bio": "Developer",
    "avatar": null
  }
}

Collez cela dans le Générateur d'interfaces TypeScript à partir de JSON et vous obtenez :

interface Profile {
  bio: string;
  avatar: null;
}

interface RootObject {
  id: number;
  username: string;
  email: string;
  createdAt: string;
  role: string;
  profile: Profile;
}

Quelques points à noter :

• Les objets imbriqués deviennent des interfaces distinctes — Profile est extraite automatiquement plutôt qu'imbriquée.
• Les dates sont typées comme string — le JSON n'a pas de type date, donc les chaînes ISO restent des chaînes. Vous devrez les parser vous-même.
• avatar: null est typée comme littérale null — ce qui est précis mais incomplet. Plus d'informations ci-dessous.

Gestion des cas complexes

Champs facultatifs

Lorsqu'un champ est null dans votre JSON d'exemple, le générateur le typé comme null. Mais en pratique, ce champ passe probablement d'une valeur réelle à null selon les données. Vous voudrez l'ajuster manuellement :

// Generated
avatar: null;

// What you actually want
avatar: string | null;

La même chose s'applique aux champs facultatifs qui sont présents dans votre exemple — ajoutez ? à toute propriété qui pourrait être absente dans certaines réponses.

Tableaux

Les tableaux d'objets sont gérés proprement. Donné :

{
  "posts": [
    { "id": 1, "title": "Hello", "published": true },
    { "id": 2, "title": "World", "published": false }
  ]
}

Le générateur produit :

interface Post {
  id: number;
  title: string;
  published: boolean;
}

interface RootObject {
  posts: Post[];
}

Types d'union

Si vos exemples JSON montrent un champ contenant des types différents selon les enregistrements — par exemple, un value qui peut être un nombre ou une chaîne — vous devriez le représenter comme une union. Les types générés ne détecteront pas cela à partir d'un seul exemple, donc il est utile de vérifier contre la documentation de l'API :

value: string | number;

Nesting profond

Le nesting profond est là où le typage manuel s'effondre — et là où les générateurs gagnent leur place. Une réponse avec trois ou quatre niveaux de nesting est décomposée en une hiérarchie propre d'interfaces nommées, chacune responsable de sa forme.

La différence entre les types au moment de compilation et la réalité en temps réel

Voici ce que les nouveaux utilisateurs de TypeScript souvent manquent : les types disparaissent au moment de l'exécution. TypeScript se compile en JavaScript, et JavaScript n'a pas de concept d'interfaces. Si votre API retourne une forme qui ne correspond pas à votre type déclaré, TypeScript ne le saura pas — et ne vous le dira pas.

Cela rend la pratique courante de caster les réponses API vraiment dangereuse :

const data = await response.json() as User; // No validation, just trust

Ce cast informe TypeScript « je vous fais confiance, c'est un User» — mais TypeScript n'a aucun moyen de le vérifier. Si l'API change sa forme ou retourne un objet d'erreur au lieu d'une réponse, votre code se casse au moment de l'exécution d'éléments que le compilateur n'a jamais prévenus.

La solution est la validation en temps réel.

Zod pour la validation en temps réel

Zod est une bibliothèque de validation de schémas, premièrement conçue pour TypeScript. Vous définissez un schéma une fois, l'utilisez pour parser les données entrantes, et obtenez une valeur typée complètement — ou un erreur détaillée si la forme ne correspond pas. Aucun casting, aucune supposition.

À l'aide du même exemple de JSON vu précédemment, le Générateur de schéma Zod à partir de JSON produit :

import { z } from "zod";

const ProfileSchema = z.object({
  bio: z.string(),
  avatar: z.null(),
});

const RootObjectSchema = z.object({
  id: z.number(),
  username: z.string(),
  email: z.string(),
  createdAt: z.string(),
  role: z.string(),
  profile: ProfileSchema,
});

type RootObject = z.infer<typeof RootObjectSchema>;

Remarquez la dernière ligne : z.infer déduit directement le type TypeScript à partir du schéma. Vous obtenez à la fois la sécurité de type au moment de compilation et la validation en temps réel à partir d'une seule source de vérité.

Utilisation à la limite de la récupération :

const rawData = await response.json();
const user = RootObjectSchema.parse(rawData); // throws if shape is wrong

// Or use safeParse to avoid throwing:
const result = RootObjectSchema.safeParse(rawData);
if (!result.success) {
  console.error(result.error.issues);
} else {
  console.log(result.data.username); // fully typed
}

Adaptez le schéma généré pour gérer les cas nuls et facultatifs que le générateur ne peut inférer à partir d'un seul exemple :

avatar: z.string().nullable(), // was z.null()
bio: z.string().optional(),    // if the field might be absent

interface vs type : Quel devriez-vous utiliser ?

Les deux interface et type Les alias peuvent représenter des formes d'objets en TypeScript, et pour la plupart des typages de réponses API, ils sont interchangeables. Les différences pratiques :

• Les interfaces peuvent être étendues et fusionnées — utile si vous souhaitez enrichir un type de base dans plusieurs fichiers. La fusion de déclarations vous permet d'ajouter des champs à une interface définie ailleurs.
• Les alias de type sont plus flexibles — ils peuvent représenter des unions, des intersections, des tuples et des types mappés, ce que les interfaces ne peuvent pas faire.
• Les messages d'erreur sont souvent plus clairs avec les interfaces — TypeScript développe les alias de type dans les messages d'erreur, ce qui peut rendre les erreurs profondément imbriquées plus difficiles à lire.

Pour les formes de réponses API, les deux fonctionnent. Choisissez interface si vous prévoyez d'étendre le type ; utilisez type si vous avez besoin de sémantiques de union ou d'intersection. La cohérence au sein d'un codebase est plus importante que le choix que vous faites.

Le workflow pratique

Voici un workflow qui prend des minutes au lieu d'une après-midi :

1. Obtenez une réponse réelle. Utilisez le panneau réseau de votre navigateur, Postman ou curl pour capturer une réponse réelle à une API. Plus la réponse est complète, meilleure seront les types générés.
2. Générez l'interface TypeScript. Collez le JSON dans le Générateur d'interfaces TypeScript à partir de JSON. Copiez le résultat dans votre projet.
3. Générez le schéma Zod. Collez le même JSON dans le Générateur de schéma Zod à partir de JSON. Copiez ce résultat dans votre projet aussi.
4. Vérifiez les champs facultatifs et nuls. Examinez le résultat généré pour les champs typés comme littéraux null ou les champs pouvant être absents. Mettez-les à string | null, .nullable(), ou .optional() selon le besoin.
5. Validez à la limite de la récupération. Remplacez toute as YourType par YourSchema.parse() ou safeParse(). Maintenant, le type est garanti de correspondre, et non simplement supposé.

C'est le cycle complet — de JSON brut à la sécurité au moment de compilation et aux garanties en temps réel en quelques minutes.

Vous aimerez peut-être aussi