Arrêtez d'écrire des interfaces TypeScript à la main : générez-les automatiquement à partir de JSON

Chaque fois que vous intégrez une nouvelle API, vous finissez par regarder une réponse JSON et saisir une interface à la main. Champ par champ. Deviner quelles valeurs sont facultatives. Oublier ça created_at est une chaîne, pas une date. Copier-coller à partir de documents qui peuvent ou non correspondre à la vraie réponse.

C'est fastidieux, lent et une source fiable de bugs. Le JSON contient déjà tous les types dont vous avez besoin. Un seul appel API peut les extraire.

Une requête POST, une interface TypeScript

Envoyez n'importe quel objet JSON au Botoi json-to-typescript point de terminaison avec un nom pour l’interface racine. L'API renvoie l'interface TypeScript complète sous forme de chaîne.

curl -X POST https://api.botoi.com/v1/schema/json-to-typescript \\
  -H "Content-Type: application/json" \\
  -d '{
    "json": {
      "id": 1,
      "name": "Acme Corp",
      "active": true,
      "tags": ["saas", "b2b"]
    },
    "name": "Company"
  }'

Réponse:

{
  "success": true,
  "data": {
    "typescript": "interface Company {\\n  id: number;\\n  name: string;\\n  active: boolean;\\n  tags: string[];\\n}",
    "name": "Company"
  }
}

L'interface générée, au format :

interface Company {
  id: number;
  name: string;
  active: boolean;
  tags: string[];
}

L'API déduit number, string, boolean, et string[] à partir des valeurs. Aucune annotation manuelle. Aucune supposition.

Créez un script de types à partir de l'API pour votre projet

Taper les interfaces à la main est une solution ponctuelle. La meilleure approche : un script qui récupère les réponses API en direct et génère des fichiers de type que vous pouvez valider dans votre dépôt.

Voici un script bash qui génère des types TypeScript à partir de n'importe quelle URL :

#!/bin/bash
set -euo pipefail

API="https://api.botoi.com/v1/schema/json-to-typescript"
OUT_DIR="./src/types/generated"
mkdir -p "\$OUT_DIR"

generate_type() {
  local url="\$1"
  local name="\$2"
  local file="\$3"

  echo "Fetching \$url ..."
  local json
  json=\$(curl -s "\$url")

  echo "Generating \$name interface..."
  local result
  result=\$(curl -s -X POST "\$API" \\
    -H "Content-Type: application/json" \\
    -d "{\"json\": \$json, \"name\": \"\$name\"}")

  echo "\$result" | jq -r '.data.typescript' > "\$OUT_DIR/\$file"
  echo "Wrote \$OUT_DIR/\$file"
}

generate_type "https://api.github.com/users/octocat" "GitHubUser" "github-user.ts"
generate_type "https://jsonplaceholder.typicode.com/posts/1" "BlogPost" "blog-post.ts"

echo "Done. All types written to \$OUT_DIR/"

Exécutez ce script pendant le développement ou en tant que hook de pré-validation. Lorsque l'API en amont change, réexécutez le script et vos types restent précis.

Si vous préférez Node.js à bash :

import { writeFileSync, mkdirSync } from "fs";

const API = "https://api.botoi.com/v1/schema/json-to-typescript";

async function generateType(json: unknown, name: string): Promise<string> {
  const res = await fetch(API, {
    method: "POST",
    headers: { "Content-Type": "application/json" },
    body: JSON.stringify({ json, name }),
  });
  const data = await res.json();
  return data.data.typescript;
}

async function main() {
  const userRes = await fetch("https://api.github.com/users/octocat");
  const userJson = await userRes.json();

  const typescript = await generateType(userJson, "GitHubUser");

  mkdirSync("./src/types/generated", { recursive: true });
  writeFileSync("./src/types/generated/github-user.ts", typescript);
  console.log("Wrote ./src/types/generated/github-user.ts");
}

main();

Exemple réel : générer des types pour la réponse utilisateur de l'API GitHub

Le GitHub /users/:username le point de terminaison renvoie plus de 30 champs. Écrire cette interface à la main prend quelques minutes et invite aux fautes de frappe. Voici l’approche en deux étapes :

# Fetch the GitHub user JSON
GITHUB_JSON=\$(curl -s https://api.github.com/users/octocat)

# Send it to the Botoi API
curl -s -X POST https://api.botoi.com/v1/schema/json-to-typescript \\
  -H "Content-Type: application/json" \\
  -d "{\"json\": \$GITHUB_JSON, \"name\": \"GitHubUser\"}" \\
  | jq -r '.data.typescript'

Sortir:

interface GitHubUser {
  login: string;
  id: number;
  node_id: string;
  avatar_url: string;
  gravatar_id: string;
  url: string;
  html_url: string;
  followers_url: string;
  following_url: string;
  gists_url: string;
  starred_url: string;
  subscriptions_url: string;
  organizations_url: string;
  repos_url: string;
  events_url: string;
  received_events_url: string;
  type: string;
  site_admin: boolean;
  name: string;
  company: string;
  blog: string;
  location: string;
  bio: string;
  twitter_username: string;
  public_repos: number;
  public_gists: number;
  followers: number;
  following: number;
  created_at: string;
  updated_at: string;
}

Cela représente 32 champs, saisis correctement, en moins d'une seconde. Transférez la sortie dans un fichier et vous avez une définition de type prête pour la production.

Générez plutôt des schémas Zod

Les interfaces TypeScript vous offrent une sécurité au moment de la compilation, mais elles disparaissent au moment de l'exécution. Si vous avez besoin d'une validation d'exécution, le json-to-zod le point de terminaison génère un schéma Zod à partir de la même entrée JSON.

curl -s -X POST https://api.botoi.com/v1/schema/json-to-zod \\
  -H "Content-Type: application/json" \\
  -d '{
    "json": {
      "id": 1,
      "name": "Acme Corp",
      "active": true,
      "tags": ["saas", "b2b"]
    },
    "name": "Company"
  }' | jq -r '.data.zod'

Sortir:

import { z } from "zod";

const Company = z.object({
  id: z.number(),
  name: z.string(),
  active: z.boolean(),
  tags: z.array(z.string()),
});

Déposez le schéma généré dans votre base de code et vous obtenez à la fois la validation d'exécution et l'inférence de type :

import { z } from "zod";

const Company = z.object({
  id: z.number(),
  name: z.string(),
  active: z.boolean(),
  tags: z.array(z.string()),
});

type Company = z.infer<typeof Company>;

const parsed = Company.parse(apiResponse);
// parsed is fully typed and validated at runtime

Avec Zod, les données invalides sont rejetées à la limite au lieu de provoquer des bugs silencieux au plus profond de la logique de votre application.

Quand utiliser chaque point de terminaison

Scénario	Point de terminaison	Pourquoi
Des réponses API internes auxquelles vous faites confiance	json-to-typescript	Léger; aucun coût d'exécution
Réponses de l'API externe	json-to-zod	Valide les données à la frontière
Entrées de formulaire ou données soumises par l'utilisateur	json-to-zod	Analyser, ne pas valider
Prototypage rapide	json-to-typescript	Chemin le plus rapide vers le code saisi
Génération de type de pipeline CI	Soit	Les deux produisent une sortie déterministe

Points clés

• Une requête remplace la saisie manuelle. Envoyez du JSON, récupérez une interface TypeScript ou un schéma Zod.
• Automatisez-le. Ajoutez un script à votre projet qui régénère les types chaque fois que les API en amont changent.
• Aucun compte requis. Le niveau gratuit autorise 5 requêtes par minute sans inscription.
• Fonctionne avec n'importe quelle source JSON. API REST, fichiers de configuration, exportations de bases de données, charges utiles de webhook.

La documentation complète sur l'API couverture points de terminaison de schéma supplémentaires, notamment json-to-jsonschema pour la sortie du schéma JSON.