Konversikan respons JSON apa pun ke skema Zod dengan satu permintaan POST

Anda menekan API pihak ketiga, mendapatkan respons JSON, dan sekarang Anda memerlukan skema Zod untuk itu. Proses manualnya: tatap responsnya, hitung bidangnya, cari tahu bidang mana yang dapat dibatalkan, tangani objek yang disarangkan, mengetik z.object Dan z.string() untuk setiap properti. Satu kesalahan ketik dan milikmu validasi secara diam-diam meneruskan data yang buruk.

Untuk benda datar dengan lima bidang, hal ini memerlukan waktu beberapa menit. Untuk tujuan pembayaran Stripe dengan biaya bertingkat, metadata, dan 30+ bidang, dibutuhkan waktu yang cukup lama hingga Anda mulai mempertanyakan pilihan karier Anda.

Botoi itu /v1/schema/json-to-zod titik akhir menghilangkan ini. POST JSON apa pun, dapatkan yang lengkap Skema Zod kembali. Satu permintaan, tidak ada CLI untuk diinstal, tidak ada paket npm untuk dikonfigurasi.

Panggilan API

Kirim objek JSON dan nama skema opsional:

keriting

Tanggapan:

Node.js

ular piton

Titik akhir menerima JSON apa pun yang valid di json bidang. Objek, array, bersarang dalam struktur; semuanya berfungsi. Itu name bidang bersifat opsional dan defaultnya adalah "Root".

Contoh nyata: maksud pembayaran Stripe

Ini adalah Stripe yang realistis payment_intent respons dengan bersarang metadata Dan charges objek. Ini adalah jenis muatan tempat skema Zod ditulis tangan menjadi menyakitkan dengan cepat.

Badan permintaan:

API mengembalikan skema Zod ini:

Setiap objek yang disarangkan menjadi miliknya sendiri z.object. Itu charges.data array menghasilkan sebuah z.array dengan bentuk barang yang benar. Boolean, angka, dan string terdeteksi nilai-nilai. Salin ini ke basis kode Anda, tambahkan import { "z" } from "zod", dan kamu punya jenis yang divalidasi waktu proses untuk respons Stripe dalam waktu kurang dari 30 detik.

Juga berfungsi untuk antarmuka TypeScript

Jika Anda memerlukan tipe TypeScript tanpa validasi runtime, /v1/schema/json-to-typescript titik akhir menghasilkan antarmuka dari input JSON yang sama.

Tanggapan:

Format masukan yang sama, sama name parameter. Menggunakan json-to-zod ketika Anda membutuhkannya validasi runtime (penanganan API, penguraian formulir, muatan webhook). Menggunakan json-to-typescript ketika Anda hanya membutuhkan keamanan tipe waktu kompilasi.

Buat skrip codegen untuk proyek Anda

Kekuatan sebenarnya muncul saat Anda mengotomatiskan pembuatan skema. Skrip ini mengambil respons API langsung, mengonversi masing-masing skema Zod, dan menulis hasilnya ke skema Zod Anda src/schemas/ direktori.

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

Menjalankannya:

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.

Setiap file yang dihasilkan terlihat seperti ini:

Tambahkan skrip ini ke file Anda package.json sebagai "codegen:schemas" dan menjalankannya setiap kali API upstream berubah. Skema Zod Anda tetap sinkron dengan bentuk respons sebenarnya, dan tipe TypeScript diturunkan dari skema secara otomatis.

Ketika ini berguna

• Melakukan orientasi API pihak ketiga yang baru. Tekan API sekali, ubah respons menjadi Zod skema, dan mulai membangun dengan tipe yang divalidasi alih-alih menebak nama bidang.
• Memigrasikan JavaScript ke TypeScript. Jika Anda memiliki respons API yang mengalir kode yang belum diketik, buat skema dari data nyata untuk mendapatkan cakupan tipe dengan cepat.
• Menjaga skema tetap sinkron. Jalankan skrip codegen di CI sesuai jadwal untuk dideteksi ketika API upstream mengubah bentuk responsnya.
• Pembuatan prototipe. Ketika Anda memerlukan tipe yang divalidasi untuk bukti konsep dan tidak menginginkannya untuk menghabiskan waktu membuat skema untuk API yang mungkin Anda buang minggu depan.