文档助手：JSON To JSDoc注释 — Numio

根据 JSON 示例生成 JSDoc @typedef 注释，每个键一行 @property。嵌套键使用 address.city 这样的点路径，数组元素的键使用 name[].key，可选键用 [方括号] 表示。

在纯 JavaScript 项目中为 API 响应获得编辑器自动补全。

JSON

JSDoc

适用场景

在纯 JavaScript 项目中为 API 响应获得编辑器自动补全。
不迁移到 TypeScript，也能对 JSON 数据启用 // @ts-check 类型检查。

使用方法

把 JSON 对象粘贴到编辑器中。
检查右侧的 @property 行：类型来自示例值，例如 tags 为 string[]，address 为 object。
复制注释，把 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}。

像 001 这样的 ID 请在输入中保持为字符串；一旦解析为数字，前导零就会丢失。

FAQ

对象数组如何记录？

数组类型为 object[]，元素的键以 name[].key 路径列出，例如 orders[].sku，并合并所有元素的键。

能转换根节点为数组的 JSON 吗？

可以。元素结构变为带属性的 @typedef {object} jsonItem，随后是表示数组的 @typedef {jsonItem[]} json。

TypeScript 能理解生成的 typedef 吗？

能。启用 checkJs 或 // @ts-check 时，TypeScript 会读取 .js 文件中带嵌套 @property 路径的 @typedef。请先把单独的 {null} 替换为实际类型。

规范与参考资料

JSDoc: @typedef