Deje de escribir interfaces TypeScript a mano: generelas automáticamente desde JSON

Cada vez que integras una nueva API, terminas mirando una respuesta JSON y escribiendo una interfaz a mano. Campo por campo. Adivinar qué valores son opcionales. olvidando eso created_at es una cadena, no una fecha. Copiar y pegar de documentos que pueden coincidir o no con la respuesta real.

Esto es tedioso, lento y una fuente confiable de errores. El JSON ya contiene todos los tipos que necesita. Una única llamada a la API puede extraerlos.

Una solicitud POST, una interfaz TypeScript

Envía cualquier objeto JSON al Botoi json-to-typescript punto final con un nombre para la interfaz raíz. La API devuelve la interfaz TypeScript completa como una cadena.

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

Respuesta:

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

La interfaz generada, formateada:

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

La API infiere number, string, boolean, y string[] a partir de los valores. Sin anotaciones manuales. Sin adivinanzas.

Cree un script de tipos desde API para su proyecto

Escribir interfaces a mano es una solución única. El mejor enfoque: un script que obtiene respuestas API en vivo y genera archivos de tipo que puede enviar a su repositorio.

Aquí hay un script bash que genera tipos de TypeScript desde cualquier URL:

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

Ejecute este script durante el desarrollo o como enlace previo a la confirmación. Cuando la API ascendente cambia, Vuelva a ejecutar el script y sus tipos seguirán siendo precisos.

Si prefieres Node.js a 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();

Ejemplo real: generar tipos para la respuesta del usuario de la API de GitHub

La GitHub /users/:username El punto final devuelve más de 30 campos. Escribiendo esa interfaz a mano Toma minutos e invita a errores tipográficos. Aquí está el enfoque de dos pasos:

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

Producción:

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

Son 32 campos, escritos correctamente, en menos de un segundo. Canalice la salida a un archivo y tendrá una definición de tipo lista para producción.

En su lugar, genere esquemas Zod

Las interfaces TypeScript le brindan seguridad en tiempo de compilación, pero desaparecen en tiempo de ejecución. Si necesita validación en tiempo de ejecución, el json-to-zod El punto final genera un esquema Zod a partir de la misma entrada JSON.

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'

Producción:

import { z } from "zod";

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

Coloque el esquema generado en su código base y obtendrá validación en tiempo de ejecución e inferencia de tipos:

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

Con Zod, los datos no válidos llegan al límite en lugar de causar errores silenciosos en lo profundo de la lógica de su aplicación.

Cuándo utilizar cada punto final

Guión	Punto final	Por qué
Respuestas API internas en las que confía	json-to-typescript	Ligero; sin costo de tiempo de ejecución
Respuestas API externas	json-to-zod	Valida datos en el límite.
Entradas de formulario o datos enviados por el usuario	json-to-zod	Analizar, no validar
creación rápida de prototipos	json-to-typescript	La ruta más rápida al código escrito
Generación de tipo de canalización de CI	Cualquiera	Ambos producen resultados deterministas.

Puntos clave

• Una solicitud reemplaza la escritura manual. Envíe JSON, recupere una interfaz TypeScript o un esquema Zod.
• Automatízalo. Agregue una secuencia de comandos a su proyecto que regenere tipos cada vez que cambien las API ascendentes.
• No se requiere cuenta. El nivel gratuito permite 5 solicitudes por minuto sin registro.
• Funciona con cualquier fuente JSON. API REST, archivos de configuración, exportaciones de bases de datos, cargas útiles de webhooks.

La documentos API completos cubrir puntos finales de esquema adicionales, incluidos json-to-jsonschema para la salida del esquema JSON.