JSON para TypeScript
Gere interfaces TypeScript a partir de um exemplo de JSON.
Sobre esta ferramenta
Cole uma resposta JSON e obtenha interfaces TypeScript para ela. Objetos aninhados viram interfaces nomeadas próprias, arrays de objetos são mesclados para que os campos opcionais sejam marcados com ?, e valores mistos viram tipos de união.
Como usar
- Cole um exemplo de resposta JSON da sua API.
- Defina o nome do tipo raiz, por exemplo User ou OrderResponse.
- Escolha declarações interface ou type, e se elas devem ser exportadas.
- Copie o TypeScript gerado para o seu projeto e ajuste o que o exemplo não conseguiu mostrar.
Perguntas
- Como os campos opcionais são detectados?
- Quando um array contém vários objetos, um campo que falta em alguns deles é marcado como opcional com ?. Um único objeto não revela campos opcionais, então use um exemplo com vários itens se puder.
- Por que um campo tem o tipo null?
- Porque ele era null no exemplo, então o tipo real é desconhecido. Substitua por algo como string | null quando souber o que a API retorna.
- Devo usar interface ou type?
- Ambos servem para descrever JSON. Interfaces podem ser estendidas e mescladas e geram mensagens de erro um pouco mais claras; aliases de tipo são necessários para uniões. Use o que sua base de código já usa.
- Ele valida os dados em tempo de execução?
- Não. Os tipos do TypeScript desaparecem na compilação. Para verificar dados em tempo de execução, use uma biblioteca de schemas como Zod junto com esses tipos.
- O que acontece se a raiz do JSON for um array?
- A raiz vira um type alias para um array. Com o nome da raiz User e uma amostra como [{"id": 1}], você obtém type User = UserItem[] mais uma interface UserItem para os elementos. Dê à raiz um nome no plural, como Users, para obter type Users = User[].
- Posso colar um objeto JavaScript em vez de JSON estrito?
- Sim. Aspas simples, chaves sem aspas, vírgulas finais e os True, False e None do Python são convertidos para JSON antes de os tipos serem gerados, então funciona a saída copiada do console.log no Node ou de um shell Python. Valores que o JSON não consegue expressar, como funções ou instâncias de classe, continuam causando erro.
- Por que o tipo de um elemento de array se chama DataItem?
- Os tipos dos elementos recebem o nome da chave do array no singular: users gera User e entries gera Entry. Quando a chave não tem terminação de plural, como data ou children, Item é acrescentado ao nome, o que gera DataItem e ChildrenItem. Se preferir outros nomes, renomeie-os no seu editor depois de colar.
Como gerar interfaces TypeScript a partir de JSON
Cole uma resposta real de API e cada objeto JSON vira uma interface TypeScript nomeada. Os nomes dos campos são mantidos, os valores viram string, number e boolean, e um objeto aninhado ganha sua própria declaração com o nome da chave, então um campo address gera uma interface Address. Arrays de objetos recebem nome no singular: orders gera Order[] e categories gera Category[]. Defina o nome da raiz como o tipo que seu código vai usar, como User.
O TypeScript gerado compila do jeito que está, então você pode colá-lo em um arquivo types.ts ou baixá-lo. Chaves que não são identificadores válidos, como "first-name" ou "2fa", são escritas entre aspas. Quando dois objetos aninhados receberiam o mesmo nome, o segundo ganha um número, como Address2. Um array vazio vira unknown[] e um objeto vazio vira Record<string, unknown>, porque a amostra não mostra nada sobre o conteúdo deles.
Como os union types são inferidos a partir do JSON
Quando o mesmo campo guarda tipos diferentes de valores, seu tipo vira uma união. Um array como [1, "two", null] é tipado como (string | number | null)[], e um campo que é string em um item e number em outro vira string | number. Objetos dentro do mesmo array são mesclados em uma única interface, e não em uma união de formatos, e os campos que aparecem só em alguns deles são marcados como opcionais.
A mesclagem funciona bem para listas de registros, mas esconde tagged unions. Se um array events mistura {"type": "click", "x": 3} e {"type": "key", "code": "Enter"}, você recebe uma única interface Event com type como string e x e code opcionais. Reescreva à mão como uma discriminated union de duas interfaces, uma com type: "click" e outra com type: "key", para que o TypeScript consiga fazer narrowing pelo campo type.
JSON para TypeScript a partir de uma amostra ou de um schema
Uma amostra JSON mostra uma resposta, não o contrato. Strings que na verdade são datas, enums como "active" | "banned", IDs numéricos que podem passar de 2^53 e campos que só aparecem às vezes não podem ser vistos em um único exemplo. Trate as interfaces geradas como um primeiro rascunho: cole uma resposta com vários itens no array e depois refine os tipos onde você sabe mais, por exemplo trocando status: string por uma união dos valores permitidos.
Se uma API publica um documento OpenAPI ou um JSON Schema, gere os tipos a partir dele, porque ele descreve todos os campos que o servidor pode devolver. Gerar tipos a partir de JSON é o caminho rápido para APIs de terceiros sem spec, payloads de webhook e endpoints internos antigos. Para dados que você não controla, adicione uma verificação em tempo de execução com o mesmo formato, como um schema Zod, para que uma resposta alterada falhe de forma explícita em vez de passar despercebida.
Algo não está funcionando ou um resultado parece errado? Relatar um problema com esta ferramenta