Converta qualquer resposta JSON em um esquema Zod com uma solicitação POST

Você acessa uma API de terceiros, obtém uma resposta JSON e agora precisa de um esquema Zod para isso. O processo manual: observe a resposta, conte os campos, descubra quais são anuláveis, manipule objetos aninhados, digite z.object e z.string() para cada propriedade. Um erro de digitação e seu a validação passa silenciosamente dados incorretos.

Para um objeto plano de cinco campos, isso leva alguns minutos. Para uma intenção de pagamento Stripe com cobranças aninhadas, metadados e mais de 30 campos, leva tempo suficiente para você começar a questionar suas escolhas de carreira.

O botoi /v1/schema/json-to-zod endpoint elimina isso. POST qualquer JSON, obtenha um completo Esquema Zod de volta. Uma solicitação, sem CLI para instalar, sem pacote npm para configurar.

A chamada da API

Envie um objeto JSON e um nome de esquema opcional:

enrolar

Resposta:

Node.js

Pitão

O endpoint aceita qualquer JSON válido no json campo. Objetos, matrizes, profundamente aninhados estruturas; tudo funciona. O name campo é opcional e o padrão é "Root".

Exemplo real: uma intenção de pagamento Stripe

Aqui está uma listra realista payment_intent resposta com aninhado metadata e charges objetos. Este é o tipo de carga útil onde esquemas Zod escritos à mão fica doloroso rapidamente.

Corpo da solicitação:

A API retorna este esquema Zod:

Cada objeto aninhado se torna seu z.object. O charges.data matriz produz um z.array com o formato correto do item. Booleanos, números e strings são detectados a partir de os valores. Copie isso em sua base de código, adicione import { "z" } from "zod", e você tem tipos validados em tempo de execução para respostas Stripe em menos de 30 segundos.

Também funciona para interfaces TypeScript

Se você precisar de tipos TypeScript sem validação de tempo de execução, o /v1/schema/json-to-typescript endpoint gera interfaces a partir da mesma entrada JSON.

Resposta:

Mesmo formato de entrada, mesmo name parâmetro. Usar json-to-zod quando você precisar validação de tempo de execução (manipuladores de API, análise de formulário, cargas úteis de webhook). Usar json-to-typescript quando você só precisa de segurança do tipo em tempo de compilação.

Crie um script codegen para seu projeto

O verdadeiro poder aparece quando você automatiza a geração de esquemas. Este script busca respostas da API ao vivo, converte cada um em um esquema Zod e grava a saída em seu src/schemas/ diretório.

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

Executando:

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.

Cada arquivo gerado se parece com isto:

Adicione este script ao seu package.json como "codegen:schemas" e executá-lo sempre que a API upstream for alterada. Seus esquemas Zod permanecem sincronizados com o formato de resposta real, e os tipos TypeScript são derivados do esquema automaticamente.

Quando isso é útil

• Integrando uma nova API de terceiros. Acesse a API uma vez e converta a resposta em um Zod esquema e comece a construir com tipos validados em vez de adivinhar nomes de campos.
• Migrando JavaScript para TypeScript. Se você tiver respostas de API fluindo código não digitado, gere esquemas a partir de dados reais para obter cobertura de tipo rapidamente.
• Mantendo os esquemas sincronizados. Execute o script codegen no CI de acordo com uma programação para detectar quando uma API upstream altera seu formato de resposta.
• Prototipagem. Quando você precisar de tipos validados para uma prova de conceito e não quiser gastar tempo criando esquemas para APIs que você poderá descartar na próxima semana.