Guía de conversión de JSON a tipos TypeScript

Por qué convertir JSON a tipos TypeScript

En la colaboración frontend-backend, las respuestas de API suelen estar en formato JSON. Escribir interfaces TypeScript manualmente es tedioso y propenso a errores, especialmente cuando las interfaces tienen muchos campos y anidación profunda. La generación automática de definiciones de tipos puede:

• Reducir el esfuerzo de escribir interfaces a mano
• Prevenir errores tipográficos en nombres de campos
• Mantener la consistencia de tipos entre frontend y backend
• Acelerar el autocompletado y la refactorización de código

Reglas básicas de conversión

Objeto simple

{
  "id": 1,
  "name": "Alice",
  "active": true
}

Resultado generado:

interface RootObject {
  id: number;
  name: string;
  active: boolean;
}

Reglas de mapeo de tipos

Valor JSON	Tipo TypeScript
"hello"	string
42	number
3.14	number
true / false	boolean
null	null
[1, 2, 3]	number[]
{"a": 1}	Interfaz anidada

Uso de la Herramienta JSON→TypeScript

Paso 1: Obtener datos JSON

Copia la respuesta de la API desde el panel Network de las DevTools del navegador, o pega datos JSON existentes directamente.

Paso 2: Abrir la herramienta

Navega a la Herramienta JSON→TypeScript y pega tu JSON en el área de entrada.

Paso 3: Configurar opciones de generación

• Nombre de la interfaz raíz: Por defecto es RootObject; usa un nombre semántico como UserInfo
• Modificador de exportación: Elige interface o type
• Campos opcionales: Si los campos con valores null se marcan como opcionales (?)
• Modificador readonly: Si se añade readonly a todos los campos

Paso 4: Generar y copiar

Haz clic en el botón de generación. La definición de tipo TypeScript aparece al instante — cópiala al portapapeles con un clic.

Manejo de objetos anidados

El JSON profundamente anidado se divide automáticamente en múltiples interfaces:

{
  "user": {
    "profile": {
      "avatar": "url",
      "bio": "text"
    }
  }
}

Resultado generado:

interface Profile {
  avatar: string;
  bio: string;
}

interface User {
  profile: Profile;
}

interface RootObject {
  user: User;
}

Se recomienda dividir las interfaces generadas en archivos separados, organizados por módulo.

Manejo de tipos de unión

Cuando un array contiene elementos de diferentes tipos:

{
  "items": ["text", 42, true]
}

La herramienta genera un tipo de unión:

interface RootObject {
  items: (string | number | boolean)[];
}

Manejo de campos opcionales

Algunos campos en las respuestas de API pueden estar ausentes. Enfoques comunes:

• Cuando el valor de un campo es null, márcalo como opcional: bio?: string | null
• Cuando un campo falta, márcalo como opcional: bio?: string
• Activa "Marcar campos null como opcionales" en la herramienta para manejar esto automáticamente

En la práctica: Generar tipos desde una API real

1. Abre las DevTools del navegador → panel Network
2. Encuentra la solicitud de API objetivo, clic derecho → Copiar respuesta
3. Pega en la Herramienta JSON→TypeScript
4. Establece el nombre de la interfaz raíz (ej. ApiResponse)
5. Copia el resultado generado al directorio types/ de tu proyecto

Problemas comunes

Problema	Causa	Solución
Tipos demasiado específicos	Inferidos de una sola muestra de datos	Añadir más datos de muestra
Anidación demasiado profunda	Estructura JSON compleja	Fusionar manualmente algunas interfaces
Tipos de elementos de array inconsistentes	Arrays de tipos mixtos	Usar tipos de unión o genéricos
Fechas se convierten en string	JSON no tiene tipo fecha	Cambiar manualmente al tipo Date

Consejos avanzados

1. Formatea el JSON con el Formateador JSON antes de generar tipos
2. Usa el mismo enfoque con la Herramienta JSON→Go para generar structs de Go
3. Combina las interfaces generadas con Zod para validación en tiempo de ejecución
4. Para proyectos grandes, usa openapi-typescript para generar desde Swagger

Resumen

La generación automática de tipos TypeScript a partir de JSON es una forma poderosa de mejorar la eficiencia del desarrollo. La Herramienta JSON→TypeScript te permite completar definiciones de tipos en segundos, evitando la tediosidad y los errores de la escritura manual. Combinada con las técnicas de anidación y campos opcionales de esta guía, puedes manejar cualquier escenario complejo.