Konvertieren Sie jede JSON-Antwort mit einer POST-Anfrage in ein Zod-Schema

Sie rufen eine Drittanbieter-API auf, erhalten eine JSON-Antwort und benötigen nun ein Zod-Schema dafür. Der manuelle Prozess: auf die Antwort starren, die Felder zählen, herausfinden, welche nullwertfähig sind, mit verschachtelten Objekten umgehen, austippen z.object Und z.string() für jede Immobilie. Ein Tippfehler und Ihr Die Validierung übergibt fehlerhafte Daten stillschweigend.

Bei einem flachen Fünf-Felder-Objekt dauert dies einige Minuten. Für eine Stripe-Zahlungsabsicht mit verschachtelten Gebühren: Metadaten und mehr als 30 Felder benötigen, dauert es lange genug, bis Sie anfangen, Ihre Berufswahl in Frage zu stellen.

Die Botoi /v1/schema/json-to-zod Endpoint beseitigt dies. POSTEN Sie einen beliebigen JSON-Code und erhalten Sie ein vollständiges Ergebnis Zod-Schema zurück. Eine Anfrage, keine zu installierende CLI, kein zu konfigurierendes NPM-Paket.

Der API-Aufruf

Senden Sie ein JSON-Objekt und einen optionalen Schemanamen:

Locken

Antwort:

Node.js

Python

Der Endpunkt akzeptiert jedes gültige JSON im json Feld. Objekte, Arrays, tief verschachtelt Strukturen; es funktioniert alles. Der name Das Feld ist optional und standardmäßig auf "Root".

Echtes Beispiel: eine Stripe-Zahlungsabsicht

Hier ist ein realistischer Streifen payment_intent Antwort mit verschachtelt metadata Und charges Objekte. Dies ist die Art von Nutzlast, bei der Zod-Schemata von Hand geschrieben werden wird schnell schmerzhaft.

Anfragetext:

Die API gibt dieses Zod-Schema zurück:

Jedes verschachtelte Objekt wird zu seinem eigenen z.object. Der charges.data Array erzeugt a z.array mit der richtigen Artikelform. Boolesche Werte, Zahlen und Zeichenfolgen werden erkannt die Werte. Kopieren Sie dies in Ihre Codebasis und fügen Sie hinzu import { "z" } from "zod", und das hast du Laufzeitvalidierte Typen für Stripe-Antworten in weniger als 30 Sekunden.

Funktioniert auch für TypeScript-Schnittstellen

Wenn Sie TypeScript-Typen ohne Laufzeitvalidierung benötigen, ist die /v1/schema/json-to-typescript Der Endpunkt generiert Schnittstellen aus derselben JSON-Eingabe.

Antwort:

Gleiches Eingabeformat, gleich name Parameter. Verwenden json-to-zod wenn Sie es brauchen Laufzeitvalidierung (API-Handler, Formularanalyse, Webhook-Nutzdaten). Verwenden json-to-typescript wenn Sie nur Typsicherheit zur Kompilierungszeit benötigen.

Erstellen Sie ein Codegen-Skript für Ihr Projekt

Die wahre Stärke zeigt sich, wenn Sie die Schemagenerierung automatisieren. Dieses Skript ruft Live-API-Antworten ab. konvertiert jedes in ein Zod-Schema und schreibt die Ausgabe in Ihr src/schemas/ Verzeichnis.

#!/bin/bash
set -euo pipefail

API_BASE="https://api.botoi.com/v1"
OUTPUT_DIR="./src/schemas"

mkdir -p "\$OUTPUT_DIR"

generate_schema() {
  local name=\$1
  local url=\$2
  local output_file="\$OUTPUT_DIR/\$(echo "\$name" | tr '[:upper:]' '[:lower:]').ts"

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

  echo "Generating Zod schema for \$name ..."
  local zod_response
  zod_response=\$(curl -s -X POST "\$API_BASE/schema/json-to-zod" \\
    -H "Content-Type: application/json" \\
    -d "{
      \\"json\\": \$json_response,
      \\"name\\": \\"\$name\\"
    }")

  local schema
  schema=\$(echo "\$zod_response" | jq -r '.data.zod')

  cat > "\$output_file" << SCHEMAEOF
import { z } from "zod";

\$schema

export type \$name = z.infer<typeof \${name}Schema>;
SCHEMAEOF

  echo "Wrote \$output_file"
}

# Add your API endpoints here
generate_schema "UserProfile" "https://api.example.com/users/1"
generate_schema "Order" "https://api.example.com/orders/latest"
generate_schema "Product" "https://api.example.com/products/42"

echo "Done. Generated \$(ls "\$OUTPUT_DIR"/*.ts | wc -l) schema files."

Ausführen:

Fetching https://api.example.com/users/1 ...
Generating Zod schema for UserProfile ...
Wrote ./src/schemas/userprofile.ts
Fetching https://api.example.com/orders/latest ...
Generating Zod schema for Order ...
Wrote ./src/schemas/order.ts
Fetching https://api.example.com/products/42 ...
Generating Zod schema for Product ...
Wrote ./src/schemas/product.ts
Done. Generated 3 schema files.

Jede generierte Datei sieht folgendermaßen aus:

Fügen Sie dieses Skript zu Ihrem hinzu package.json als "codegen:schemas" und führen Sie es aus immer dann, wenn sich die Upstream-API ändert. Ihre Zod-Schemata bleiben mit der tatsächlichen Reaktionsform synchron. und TypeScript-Typen werden automatisch aus dem Schema abgeleitet.

Wenn dies nützlich ist

• Onboarding einer neuen Drittanbieter-API. Klicken Sie einmal auf die API und konvertieren Sie die Antwort in einen Zod Schema, und beginnen Sie mit der Erstellung mit validierten Typen, anstatt Feldnamen zu erraten.
• Migration von JavaScript zu TypeScript. Wenn API-Antworten durchfließen Erstellen Sie untypisierten Code und generieren Sie Schemata aus echten Daten, um schnell eine Typabdeckung zu erhalten.
• Schemata synchron halten. Führen Sie das Codegen-Skript in CI nach einem Zeitplan aus, um es zu erkennen wenn eine Upstream-API ihre Antwortform ändert.
• Prototyping. Wenn Sie validierte Typen für einen Proof of Concept benötigen und nicht möchten Zeit damit zu verbringen, Schemata für APIs manuell zu erstellen, die Sie nächste Woche möglicherweise verwerfen.