Guia de Conversão de JSON para Tipos TypeScript

Por que Converter JSON para Tipos TypeScript

Na colaboração frontend-backend, as respostas de API geralmente estão em formato JSON. Escrever interfaces TypeScript manualmente é demorado e propenso a erros, especialmente quando as interfaces têm muitos campos e aninhamento profundo. A geração automática de definições de tipos pode:

• Reduzir o esforço de escrever interfaces manualmente
• Prevenir erros de digitação nos nomes dos campos
• Manter a consistência de tipos entre frontend e backend
• Acelerar o autocompletar e a refatoração de código

Regras Básicas de Conversão

Objeto Simples

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

Resultado gerado:

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

Regras de Mapeamento de Tipos

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

Usando a Ferramenta JSON→TypeScript

Passo 1: Obter Dados JSON

Copie a resposta da API do painel Network das DevTools do navegador, ou cole dados JSON existentes diretamente.

Passo 2: Abrir a Ferramenta

Navegue até a Ferramenta JSON→TypeScript e cole seu JSON na área de entrada.

Passo 3: Configurar Opções de Geração

• Nome da interface raiz: O padrão é RootObject; use um nome semântico como UserInfo
• Modificador de exportação: Escolha interface ou type
• Campos opcionais: Se campos com valores null devem ser marcados como opcionais (?)
• Modificador readonly: Se deve adicionar readonly a todos os campos

Passo 4: Gerar e Copiar

Clique no botão de geração. A definição de tipo TypeScript aparece instantaneamente — copie para a área de transferência com um clique.

Tratando Objetos Aninhados

JSON profundamente aninhado é automaticamente dividido em múltiplas interfaces:

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

Resultado gerado:

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

interface User {
  profile: Profile;
}

interface RootObject {
  user: User;
}

Recomenda-se dividir as interfaces geradas em arquivos separados, organizados por módulo.

Tratando Tipos de União

Quando um array contém elementos de tipos diferentes:

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

A ferramenta gera um tipo de união:

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

Tratando Campos Opcionais

Alguns campos nas respostas de API podem estar ausentes. Abordagens comuns:

• Quando o valor de um campo é null, marque-o como opcional: bio?: string | null
• Quando um campo está ausente, marque-o como opcional: bio?: string
• Ative "Marcar campos null como opcionais" na ferramenta para lidar com isso automaticamente

Na Prática: Gerar Tipos a Partir de uma API Real

1. Abra as DevTools do navegador → painel Network
2. Encontre a requisição de API desejada, clique com o botão direito → Copiar Resposta
3. Cole na Ferramenta JSON→TypeScript
4. Defina o nome da interface raiz (ex.: ApiResponse)
5. Copie o resultado gerado para o diretório types/ do seu projeto

Problemas Comuns

Problema	Causa	Solução
Tipos muito específicos	Inferidos de uma única amostra de dados	Adicionar mais dados de amostra
Aninhamento muito profundo	Estrutura JSON complexa	Mesclar manualmente algumas interfaces
Tipos inconsistentes em elementos de array	Arrays de tipos mistos	Usar tipos de união ou genéricos
Datas viram string	JSON não tem tipo data	Alterar manualmente para o tipo Date

Dicas Avançadas

1. Formate o JSON com o Formatador JSON antes de gerar tipos
2. Use a mesma abordagem com a Ferramenta JSON→Go para gerar structs Go
3. Combine as interfaces geradas com Zod para validação em tempo de execução
4. Para projetos grandes, use openapi-typescript para gerar a partir do Swagger

Resumo

A geração automática de tipos TypeScript a partir de JSON é uma forma poderosa de aumentar a eficiência do desenvolvimento. A Ferramenta JSON→TypeScript permite completar definições de tipos em segundos, evitando a tediosidade e os erros da escrita manual. Combinada com as técnicas de aninhamento e campos opcionais deste guia, você pode lidar com qualquer cenário complexo.