Convertir JSON a comentarios JSDoc — Numio
Crea un comentario JSDoc @typedef con una línea @property por clave a partir de una muestra JSON. Las claves anidadas usan rutas con punto como address.city, las claves de los elementos de un array name[].key y las claves opcionales [corchetes].
Obtener autocompletado en el editor para la respuesta de una API en un proyecto de JavaScript puro.
JSON
JSDoc
Cuándo usarla
- Obtener autocompletado en el editor para la respuesta de una API en un proyecto de JavaScript puro.
- Activar la comprobación de tipos con // @ts-check para datos JSON sin pasarse a TypeScript.
Cómo usarla
- Pega un objeto JSON en el editor.
- Revisa las líneas @property de la derecha: los tipos salen de los valores de la muestra, por ejemplo string[] para tags y object para address.
- Copia el comentario, cambia el nombre del typedef de json a uno real y úsalo con @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
*/Detalles y limitaciones
El comentario se genera en el navegador; no se envían datos a ningún servidor. No hay opciones de configuración.
Todos los elementos de un array se fusionan: las claves que faltan en algunos elementos se escriben entre corchetes como opcionales, como [orders[].gift].
Un valor que solo es null tiene tipo {null}; null junto a valores reales da una unión como {string|null}. Los arrays vacíos tienen tipo {Array}.
Deja los IDs como 001 como cadenas en la entrada; una vez parseados como números, se pierden los ceros a la izquierda.
FAQ
¿Cómo se documentan los arrays de objetos?
El array tiene tipo object[] y las claves de los elementos se listan con rutas name[].key, como orders[].sku, combinando las claves de todos los elementos.
¿Puedo convertir un array JSON en la raíz?
Sí. La forma de los elementos pasa a @typedef {object} jsonItem con sus propiedades, seguida de @typedef {jsonItem[]} json para el array.
¿TypeScript entiende el typedef generado?
Sí, TypeScript lee @typedef con rutas @property anidadas en archivos .js cuando checkJs o // @ts-check están activados. Antes, sustituye cualquier {null} suelto por el tipo real.