使用一个 POST 请求将任何 JSON 响应转换为 Zod 架构

您访问第三方 API，获得 JSON 响应，现在您需要一个 Zod 架构。 手动流程： 盯着响应，计算字段数，找出哪些字段可以为空，处理嵌套对象， 输入 z.object 和 z.string() 对于每一个财产。 一个错字和你的 验证会默默地传递错误数据。

对于平坦的五场物体，这需要几分钟。 对于具有嵌套费用的 Stripe 付款意图， 元数据和 30 多个字段，需要很长时间才能让您开始质疑自己的职业选择。

波托伊 /v1/schema/json-to-zod 端点消除了这一点。 POST 任何 JSON，获得完整的 Zod 架构回来了。 一个请求，无需安装 CLI，无需配置 npm 包。

API 调用

发送 JSON 对象和可选的架构名称：

卷曲

回复：

Node.js

Python

端点接受任何有效的 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 处理程序、表单解析、Webhook 有效负载）。 使用 json-to-typescript 当您只需要编译时类型安全时。

为您的项目构建 codegen 脚本

当您自动生成模式时，真正的力量就会显现出来。 该脚本获取实时 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 中的 codegen 脚本来检测 当上游 API 更改其响应形状时。
• 原型制作。 当您需要经过验证的类型来进行概念验证并且不希望 花时间为 API 手工制作架构，你可能会在下周放弃。