Hören Sie auf, TypeScript-Schnittstellen manuell zu schreiben: Generieren Sie sie automatisch aus JSON

Jedes Mal, wenn Sie eine neue API integrieren, starren Sie am Ende auf eine JSON-Antwort und geben eine Schnittstelle von Hand ein. Feld für Feld. Erraten, welche Werte optional sind. Das vergessen created_at ist eine Zeichenfolge, kein Datum. Kopieren und Einfügen von Dokumenten, die möglicherweise mit der tatsächlichen Antwort übereinstimmen oder nicht.

Dies ist mühsam, langsam und eine zuverlässige Fehlerquelle. Der JSON enthält bereits jeden Typ, den Sie benötigen. Ein einziger API-Aufruf kann sie extrahieren.

Eine POST-Anfrage, eine TypeScript-Schnittstelle

Senden Sie ein beliebiges JSON-Objekt an Botoi json-to-typescript Endpunkt mit einem Namen für die Root-Schnittstelle. Die API gibt die vollständige TypeScript-Schnittstelle als String zurück.

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"
  }'

Antwort:

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

Die generierte Schnittstelle, formatiert:

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

Die API leitet daraus ab number, string, boolean, Und string[] aus den Werten. Keine manuelle Anmerkung. Kein Raten.

Erstellen Sie ein Types-from-API-Skript für Ihr Projekt

Das manuelle Eingeben von Schnittstellen ist eine einmalige Aufgabe. Der bessere Ansatz: ein Skript, das Live-API-Antworten abruft und generiert Typdateien, die Sie in Ihr Repo übernehmen können.

Hier ist ein Bash-Skript, das TypeScript-Typen aus einer beliebigen URL generiert:

#!/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/"

Führen Sie dieses Skript während der Entwicklung oder als Pre-Commit-Hook aus. Wenn sich die Upstream-API ändert, Führen Sie das Skript erneut aus und Ihre Eingaben bleiben korrekt.

Wenn Sie Node.js gegenüber Bash bevorzugen:

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();

Reales Beispiel: Generieren Sie Typen für die GitHub-API-Benutzerantwort

Der GitHub /users/:username Der Endpunkt gibt mehr als 30 Felder zurück. Schreiben Sie diese Schnittstelle von Hand dauert Minuten und lädt zu Tippfehlern ein. Hier ist der zweistufige Ansatz:

# 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'

Ausgabe:

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;
}

Das sind 32 Felder, richtig eingegeben, in weniger als einer Sekunde. Leiten Sie die Ausgabe in eine Datei um und Sie haben eine produktionsreife Typdefinition.

Generieren Sie stattdessen Zod-Schemata

TypeScript-Schnittstellen bieten Ihnen Sicherheit zur Kompilierungszeit, verschwinden jedoch zur Laufzeit. Wenn Sie eine Laufzeitvalidierung benötigen, die json-to-zod Der Endpunkt generiert ein Zod-Schema aus derselben JSON-Eingabe.

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'

Ausgabe:

import { z } from "zod";

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

Fügen Sie das generierte Schema in Ihre Codebasis ein und Sie erhalten sowohl Laufzeitvalidierung als auch Typinferenz:

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

Mit Zod stoßen ungültige Daten an die Grenze, anstatt stille Fehler tief in Ihrer Anwendungslogik zu verursachen.

Wann jeder Endpunkt verwendet werden soll

Szenario	Endpunkt	Warum
Interne API-Antworten, denen Sie vertrauen	json-to-typescript	Leicht; keine Laufzeitkosten
Externe API-Antworten	json-to-zod	Validiert Daten an der Grenze
Formulareingaben oder vom Benutzer übermittelte Daten	json-to-zod	Analysieren, nicht validieren
Schnelles Prototyping	json-to-typescript	Schnellster Weg zum eingegebenen Code
Generierung des CI-Pipeline-Typs	Entweder	Beide erzeugen eine deterministische Ausgabe

Wichtige Punkte

• Eine Anfrage ersetzt die manuelle Eingabe. Senden Sie JSON, erhalten Sie eine TypeScript-Schnittstelle oder ein Zod-Schema zurück.
• Automatisieren Sie es. Fügen Sie Ihrem Projekt ein Skript hinzu, das Typen neu generiert, wenn sich Upstream-APIs ändern.
• Kein Konto erforderlich. Das kostenlose Kontingent ermöglicht 5 Anfragen pro Minute ohne Anmeldung.
• Funktioniert mit jeder JSON-Quelle. REST-APIs, Konfigurationsdateien, Datenbankexporte, Webhook-Payloads.

Der Vollständige API-Dokumente Abdeckung zusätzliche Schema-Endpunkte, einschließlich json-to-jsonschema für die JSON-Schema-Ausgabe.