Конвертер JSON в комментарии JSDoc — Numio

Строит из примера JSON комментарий JSDoc @typedef со строкой @property для каждого ключа. Вложенные ключи записываются путями через точку, например address.city, ключи элементов массива — name[].key, необязательные ключи — в [квадратных скобках].

Получить автодополнение в редакторе для ответа API в проекте на чистом JavaScript.

JSON

JSDoc

Когда пригодится

Получить автодополнение в редакторе для ответа API в проекте на чистом JavaScript.
Включить проверку типов // @ts-check для JSON-данных без перехода на TypeScript.

Как пользоваться

Вставьте JSON-объект в редактор.
Проверьте строки @property справа: типы берутся из значений примера, например string[] для tags и object для address.
Скопируйте комментарий, переименуйте typedef json в осмысленное имя и используйте его с @type {YourName}.

Ввод 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
 */

Подробности и ограничения

Комментарий генерируется в браузере; данные на сервер не отправляются. Настроек нет.

Все элементы массива объединяются: ключи, отсутствующие в некоторых элементах, записываются в квадратных скобках как необязательные, например [orders[].gift].

Значение, которое только null, получает тип {null}; null рядом с реальными значениями даёт объединение вроде {string|null}. Пустые массивы получают тип {Array}.

Оставляйте ID вроде 001 строками во входных данных; после разбора как чисел ведущие нули теряются.

FAQ

Как документируются массивы объектов?

Массив получает тип object[], а ключи элементов перечисляются путями name[].key, например orders[].sku, с объединением ключей всех элементов.

Можно ли преобразовать JSON-массив на корневом уровне?

Да. Форма элемента становится @typedef {object} jsonItem со своими свойствами, за которым следует @typedef {jsonItem[]} json для массива.

Понимает ли TypeScript сгенерированный typedef?

Да, TypeScript читает @typedef с вложенными путями @property в файлах .js, если включён checkJs или // @ts-check. Сначала замените голый {null} на реальный тип.

Спецификации и справка

JSDoc: @typedef