Convertir JSON en annotations JSDoc — Numio

Construit un commentaire JSDoc @typedef avec une ligne @property par clé à partir d’un échantillon JSON. Les clés imbriquées utilisent des chemins pointés comme address.city, les clés des éléments de tableau name[].key, et les clés optionnelles des [crochets].

Obtenir l’autocomplétion dans l’éditeur pour une réponse d’API dans un projet JavaScript pur.

JSON

JSDoc

Quand l’utiliser

Obtenir l’autocomplétion dans l’éditeur pour une réponse d’API dans un projet JavaScript pur.
Activer la vérification de types // @ts-check pour des données JSON sans passer à TypeScript.

Mode d’emploi

Collez un objet JSON dans l’éditeur.
Vérifiez les lignes @property à droite : les types viennent des valeurs de l’échantillon, par exemple string[] pour tags et object pour address.
Copiez le commentaire, renommez le typedef json avec un vrai nom et utilisez-le avec @type {YourName}.

Entrée 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
 */

Détails et limites

Le commentaire est généré dans votre navigateur ; aucune donnée n’est envoyée à un serveur. Il n’y a pas de paramètres.

Tous les éléments d’un tableau sont fusionnés : les clés absentes de certains éléments sont écrites entre crochets comme optionnelles, par exemple [orders[].gift].

Une valeur toujours null est typée {null} ; null à côté de valeurs réelles donne une union comme {string|null}. Les tableaux vides sont typés {Array}.

Gardez les identifiants comme 001 sous forme de chaînes dans l’entrée ; une fois parsés comme nombres, les zéros initiaux sont perdus.

FAQ

Comment les tableaux d’objets sont-ils documentés ?

Le tableau est typé object[] et les clés des éléments sont listées avec des chemins name[].key, comme orders[].sku, en combinant les clés de tous les éléments.

Puis-je convertir un tableau JSON à la racine ?

Oui. La forme des éléments devient @typedef {object} jsonItem avec ses propriétés, suivi de @typedef {jsonItem[]} json pour le tableau.

TypeScript comprend-il le typedef généré ?

Oui, TypeScript lit @typedef avec des chemins @property imbriqués dans les fichiers .js quand checkJs ou // @ts-check est activé. Remplacez d’abord tout {null} isolé par le vrai type.

Spécifications et références

JSDoc: @typedef