Converter JSON em anotações JSDoc — Numio
Monta um comentário JSDoc @typedef com uma linha @property por chave a partir de uma amostra JSON. Chaves aninhadas usam caminhos com ponto como address.city, chaves de itens de array name[].key e chaves opcionais [colchetes].
Ter autocompletar no editor para a resposta de uma API em um projeto JavaScript puro.
JSON
JSDoc
Quando usar
- Ter autocompletar no editor para a resposta de uma API em um projeto JavaScript puro.
- Ativar a verificação de tipos com // @ts-check para dados JSON sem migrar para TypeScript.
Como usar
- Cole um objeto JSON no editor.
- Confira as linhas @property à direita: os tipos vêm dos valores da amostra, por exemplo string[] para tags e object para address.
- Copie o comentário, renomeie o typedef de json para um nome real e use-o com @type {YourName}.
Entrada JSON
{
"id": 42,
"name": "Ada",
"tags": ["math", "poetry"],
"address": { "city": "London", "zip": "NW1" },
"orders": [
{ "sku": "A1", "qty": 2 },
{ "sku": "B7", "qty": 1, "gift": true }
],
"deletedAt": null
}JSDoc @typedef
/**
* @typedef {object} json
* @property {number} id
* @property {string} name
* @property {string[]} tags
* @property {object} address
* @property {string} address.city
* @property {string} address.zip
* @property {object[]} orders
* @property {string} orders[].sku
* @property {number} orders[].qty
* @property {boolean} [orders[].gift]
* @property {null} deletedAt
*/Detalhes e limitações
O comentário é gerado no navegador; nenhum dado é enviado a um servidor. Não há configurações.
Todos os itens de um array são mesclados: chaves ausentes em alguns itens são escritas entre colchetes como opcionais, como [orders[].gift].
Um valor que é sempre null é tipado como {null}; null ao lado de valores reais gera uma união como {string|null}. Arrays vazios são tipados como {Array}.
Mantenha IDs como 001 como strings na entrada; depois de interpretados como números, os zeros à esquerda se perdem.
FAQ
Como arrays de objetos são documentados?
O array é tipado como object[] e as chaves dos itens são listadas com caminhos name[].key, como orders[].sku, combinando as chaves de todos os itens.
Posso converter um array JSON na raiz?
Sim. O formato do item vira @typedef {object} jsonItem com suas propriedades, seguido de @typedef {jsonItem[]} json para o array.
O TypeScript entende o typedef gerado?
Sim, o TypeScript lê @typedef com caminhos @property aninhados em arquivos .js quando checkJs ou // @ts-check está ativado. Antes, substitua qualquer {null} isolado pelo tipo real.