Guide de conversion JSON en types TypeScript

Pourquoi convertir du JSON en types TypeScript

Dans la collaboration frontend-backend, les réponses d'API sont généralement au format JSON. Écrire des interfaces TypeScript manuellement est fastidieux et source d'erreurs, surtout lorsque les interfaces comportent de nombreux champs et une imbrication profonde. La génération automatique de définitions de types permet de :

• Réduire l'effort d'écriture manuelle des interfaces
• Prévenir les fautes de frappe dans les noms de champs
• Maintenir la cohérence des types entre le frontend et le backend
• Accélérer l'autocomplétion et le refactoring du code

Règles de conversion de base

Objet simple

{
  "id": 1,
  "name": "Alice",
  "active": true
}

Résultat généré :

interface RootObject {
  id: number;
  name: string;
  active: boolean;
}

Règles de mappage des types

Valeur JSON	Type TypeScript
"hello"	string
42	number
3.14	number
true / false	boolean
null	null
[1, 2, 3]	number[]
{"a": 1}	Interface imbriquée

Utilisation de l'Outil JSON→TypeScript

Étape 1 : Obtenir les données JSON

Copiez la réponse de l'API depuis le panneau Network des DevTools du navigateur, ou collez directement des données JSON existantes.

Étape 2 : Ouvrir l'outil

Accédez à l'Outil JSON→TypeScript et collez votre JSON dans la zone de saisie.

Étape 3 : Configurer les options de génération

• Nom de l'interface racine : Par défaut RootObject ; utilisez un nom sémantique comme UserInfo
• Modificateur d'export : Choisissez interface ou type
• Champs optionnels : Si les champs avec des valeurs null doivent être marqués comme optionnels (?)
• Modificateur readonly : Si ajouter readonly à tous les champs

Étape 4 : Générer et copier

Cliquez sur le bouton de génération. La définition de type TypeScript apparaît instantanément — copiez-la dans le presse-papiers en un clic.

Traitement des objets imbriqués

Le JSON profondément imbriqué est automatiquement divisé en plusieurs interfaces :

{
  "user": {
    "profile": {
      "avatar": "url",
      "bio": "text"
    }
  }
}

Résultat généré :

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

interface User {
  profile: Profile;
}

interface RootObject {
  user: User;
}

Il est recommandé de diviser les interfaces générées dans des fichiers séparés, organisés par module.

Traitement des types union

Lorsqu'un tableau contient des éléments de types différents :

{
  "items": ["text", 42, true]
}

L'outil génère un type union :

interface RootObject {
  items: (string | number | boolean)[];
}

Traitement des champs optionnels

Certains champs dans les réponses d'API peuvent être absents. Approches courantes :

• Lorsqu'une valeur de champ est null, la marquer comme optionnelle : bio?: string | null
• Lorsqu'un champ est absent, le marquer comme optionnel : bio?: string
• Activer « Marquer les champs null comme optionnels » dans l'outil pour gérer cela automatiquement

En pratique : Générer des types à partir d'une API réelle

1. Ouvrez les DevTools du navigateur → panneau Network
2. Trouvez la requête API cible, clic droit → Copier la réponse
3. Collez dans l'Outil JSON→TypeScript
4. Définissez le nom de l'interface racine (ex. ApiResponse)
5. Copiez le résultat généré dans le répertoire types/ de votre projet

Problèmes courants

Problème	Cause	Solution
Types trop spécifiques	Déduits d'un seul échantillon de données	Ajouter plus d'échantillons de données
Imbrication trop profonde	Structure JSON complexe	Fusionner manuellement certaines interfaces
Types d'éléments de tableau incohérents	Tableaux de types mixtes	Utiliser des types union ou des génériques
Les dates deviennent string	JSON n'a pas de type date	Changer manuellement en type Date

Conseils avancés

1. Formatez le JSON avec le Formateur JSON avant de générer des types
2. Utilisez la même approche avec l'Outil JSON→Go pour générer des structs Go
3. Combinez les interfaces générées avec Zod pour la validation à l'exécution
4. Pour les grands projets, utilisez openapi-typescript pour générer à partir de Swagger

Résumé

La génération automatique de types TypeScript à partir de JSON est un moyen puissant d'améliorer l'efficacité du développement. L'Outil JSON→TypeScript vous permet de compléter les définitions de types en quelques secondes, évitant la fastidieuse et les erreurs de l'écriture manuelle. Combiné avec les techniques d'imbrication et de champs optionnels de ce guide, vous pouvez gérer n'importe quel scénario complexe.