Преобразование любого ответа JSON в схему Zod с помощью одного запроса POST.

Вы обращаетесь к стороннему API, получаете ответ в формате JSON, и теперь для него вам нужна схема Zod. Ручной процесс: смотреть на ответ, пересчитывать поля, выяснять, какие из них допускают значение NULL, обрабатывать вложенные объекты, печатать z.object и z.string() для каждого объекта недвижимости. Одна опечатка и ты проверка молча передает неверные данные.

Для плоского пятипольного объекта это занимает несколько минут. Для платежного намерения Stripe с вложенными платежами: метаданные и более 30 полей, это займет достаточно много времени, чтобы вы начали сомневаться в своем выборе карьеры.

Ботой /v1/schema/json-to-zod конечная точка устраняет это. ОТПРАВЬТЕ любой JSON, получите полную Схема Зода назад. Один запрос, не нужно устанавливать CLI и не нужно настраивать пакет npm.

API-вызов

Отправьте объект JSON и необязательное имя схемы:

завиток

Ответ:

Node.js

Питон

Конечная точка принимает любой действительный JSON в json поле. Объекты, массивы, глубоко вложенные конструкции; все это работает. name поле является необязательным и по умолчанию имеет значение "Root".

Реальный пример: платежное намерение Stripe

Вот реалистичная полоса payment_intent ответ с вложенным metadata и charges объекты. Это тот тип полезной нагрузки, в котором схемы Zod пишутся от руки. быстро становится болезненным.

Тело запроса:

API возвращает следующую схему Zod:

Каждый вложенный объект становится отдельным z.object. charges.data массив производит а z.array с правильной формой предмета. Логические значения, числа и строки обнаруживаются из ценности. Скопируйте это в свою кодовую базу, добавьте import { "z" } from "zod", и у тебя есть типы, проверенные во время выполнения, для ответов Stripe менее чем за 30 секунд.

Также работает для интерфейсов TypeScript.

Если вам нужны типы TypeScript без проверки во время выполнения, /v1/schema/json-to-typescript конечная точка генерирует интерфейсы из одного и того же ввода JSON.

Ответ:

Тот же формат ввода, тот же name параметр. Использовать json-to-zod когда тебе нужно проверка во время выполнения (обработчики API, анализ форм, полезные данные веб-перехватчика). Использовать json-to-typescript когда вам нужна только безопасность типов во время компиляции.

Создайте сценарий кодирования для вашего проекта.

Реальная мощь проявляется, когда вы автоматизируете генерацию схемы. Этот скрипт получает живые ответы API, преобразует каждый из них в схему Zod и записывает результат в ваш src/schemas/ каталог.

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

Запускаем его:

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.

Каждый сгенерированный файл выглядит следующим образом:

Добавьте этот скрипт в свой package.json как "codegen:schemas" и запусти его всякий раз, когда изменяется исходный API. Ваши схемы Zod остаются синхронизированными с реальной формой ответа. и типы TypeScript автоматически извлекаются из схемы.

Когда это полезно

• Внедрение нового стороннего API. Нажмите API один раз, преобразуйте ответ в Zod. схему и начните создавать ее с проверенными типами вместо того, чтобы угадывать имена полей.
• Миграция JavaScript в TypeScript. Если у вас есть ответы API, проходящие через нетипизированный код, генерируйте схемы на основе реальных данных, чтобы быстро получить покрытие типов.
• Синхронизация схем. Запустите сценарий создания кода в CI по расписанию, чтобы обнаружить когда вышестоящий API меняет форму своего ответа.
• Прототипирование. Если вам нужны проверенные типы для проверки концепции и вы не хотите потратить время на создание вручную схем API, от которых вы можете отказаться на следующей неделе.