Berhenti menulis antarmuka TypeScript dengan tangan: buat secara otomatis dari JSON

Setiap kali Anda mengintegrasikan API baru, Anda akhirnya melihat respons JSON dan mengetik antarmuka dengan tangan. Bidang demi bidang. Menebak nilai mana yang opsional. Lupa itu created_at adalah string, bukan Tanggal. Salin-tempel dari dokumen yang mungkin cocok atau tidak cocok dengan respons sebenarnya.

Ini membosankan, lambat, dan merupakan sumber bug yang dapat diandalkan. JSON sudah berisi semua jenis yang Anda butuhkan. Satu panggilan API dapat mengekstraknya.

Satu permintaan POST, satu antarmuka TypeScript

Kirim objek JSON apa pun ke Botoi json-to-typescript titik akhir dengan nama untuk antarmuka root. API mengembalikan antarmuka TypeScript lengkap sebagai string.

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

Tanggapan:

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

Antarmuka yang dihasilkan, diformat:

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

API menyimpulkan number, string, boolean, Dan string[] dari nilai-nilai. Tidak ada anotasi manual. Jangan menebak-nebak.

Buat skrip tipe-dari-api untuk proyek Anda

Mengetik antarmuka dengan tangan adalah perbaikan satu kali. Pendekatan yang lebih baik: skrip yang mengambil respons API langsung dan menghasilkan file tipe yang dapat Anda komit ke repo Anda.

Berikut adalah skrip bash yang menghasilkan tipe TypeScript dari URL mana pun:

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

Jalankan skrip ini selama pengembangan atau sebagai pre-commit hook. Saat API upstream berubah, jalankan kembali skrip dan tipe Anda tetap akurat.

Jika Anda lebih memilih Node.js daripada 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();

Contoh nyata: menghasilkan tipe untuk respons pengguna GitHub API

GitHub /users/:username titik akhir mengembalikan 30+ bidang. Menulis antarmuka itu dengan tangan membutuhkan waktu beberapa menit dan mengundang kesalahan ketik. Berikut adalah pendekatan dua langkah:

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

Keluaran:

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

Itu berarti 32 bidang, diketik dengan benar, dalam waktu kurang dari satu detik. Pipa output ke dalam file dan Anda punya definisi tipe siap produksi.

Hasilkan skema Zod sebagai gantinya

Antarmuka TypeScript memberi Anda keamanan waktu kompilasi, namun menghilang saat runtime. Jika Anda memerlukan validasi runtime, itu json-to-zod titik akhir menghasilkan skema Zod dari input JSON yang sama.

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'

Keluaran:

import { z } from "zod";

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

Masukkan skema yang dihasilkan ke dalam basis kode Anda dan Anda akan mendapatkan validasi runtime dan inferensi tipe:

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

Dengan Zod, data yang tidak valid muncul di batas alih-alih menyebabkan bug diam-diam di dalam logika aplikasi Anda.

Kapan menggunakan setiap titik akhir

Skenario	Titik akhir	Mengapa
Respons API internal yang Anda percayai	json-to-typescript	Ringan; tidak ada biaya waktu proses
Respons API eksternal	json-to-zod	Memvalidasi data di batas
Input formulir atau data yang dikirimkan pengguna	json-to-zod	Parsing, jangan validasi
Pembuatan prototipe cepat	json-to-typescript	Jalur tercepat ke kode yang diketik
Pembuatan tipe pipa CI	Salah satu	Keduanya menghasilkan keluaran deterministik

Poin-poin penting

• Satu permintaan menggantikan pengetikan manual. Kirim JSON, dapatkan kembali antarmuka TypeScript atau skema Zod.
• Otomatiskan itu. Tambahkan skrip ke proyek Anda yang membuat ulang tipe setiap kali API upstream berubah.
• Tidak diperlukan akun. Tingkat gratis mengizinkan 5 permintaan per menit tanpa pendaftaran.
• Bekerja dengan sumber JSON apa pun. REST API, file konfigurasi, ekspor database, payload webhook.

Itu dokumen API lengkap penutup titik akhir skema tambahan, termasuk json-to-jsonschema untuk keluaran Skema JSON.