API 响应 JSON 转 Markdown 表格 — curl + jq、分页、6 种响应结构

把 API 响应贴进 README、Issue 或内部 Wiki 的时候，原始 JSON 数据很难一眼看明白，这时候多半想转成 Markdown 表格。这篇文章讲的是怎么用 curl 把 API 响应的 JSON 拿到手，然后在浏览器里安全地转成 Markdown 表格。分页、嵌套对象、顶层不是数组这些实际会碰到的情况，都会一并处理。

最快的路径是"curl 拿响应 → jq 抽对象数组 → 转 CSV → 用 CSV to Markdown 生成表格"。顶层不是数组的响应，用 jq 定位到目标数组，或者用 [ ... ] 包一层再处理。所有转换都在浏览器内完成，即使响应里带了认证 Token 或敏感数据，也不会发到任何外部服务器。

结论：API 响应靠"抽数组"变表格

API 响应的 JSON 能不能变成 Markdown 表格，基本取决于一件事：能不能把它切成结构一致的对象数组。实际 API 返回的数据往往像下面这样，外层包了元数据，直接转表格是转不了的。

{
  "data": [
    { "id": "usr_001", "email": "mika@example.com", "active": true },
    { "id": "usr_002", "email": "noah@example.com", "active": false }
  ],
  "pagination": { "page": 1, "total": 2 }
}

这里要转表格的核心数据是 data 字段里的对象数组。从顶层定位到 data 数组，转成 CSV 格式再传过去，就能得到列头和数据行都整齐的 Markdown 表格。

工作流：curl + jq + FormatArc

整条流水线用命令串起来，每一步都能肉眼确认中间输出：

# 1. 调 API 存成 JSON 文件
curl -s -H "Authorization: Bearer $TOKEN" \
  https://api.example.com/v1/users > users.json

# 2. 贴到 JSON Formatter 看结构
#    https://formatarc.com/zh-cn/json-formatter/

# 3. 只取 data 数组，转成 CSV
jq -r '.data | (map(keys) | add | unique) as $cols
       | $cols, (.[] | [.[$cols[]]]) | @csv' users.json

# 4. 把输出的 CSV 贴到 CSV to Markdown 生成表格
#    https://formatarc.com/zh-cn/csv-to-markdown/

不想装 jq、只想在浏览器里看结构的话，先把 JSON 响应贴到 JSON Formatter，确认层级和键名。

第 1 步：获取 API 响应并格式化

如果是浏览器能直接打开的 GET 端点，把响应复制出来贴进 JSON Formatter 就行了。用 curl 的话加 -s 关掉进度条，需要认证就加 -H 带上请求头。curl 输出 JSON 的格式化方法还可以参考 curl JSON 格式化。

把响应存成文件的好处是，jq 表达式可以反复调整，不用每次都重新调 API。

curl -s -H "Authorization: Bearer $TOKEN" \
  https://api.example.com/v1/users > users.json
cat users.json | python3 -m json.tool | head

python3 -m json.tool 是不装 jq 的环境里最轻量的格式化手段。

第 2 步：抽数组、生成 CSV

看完格式化后的 JSON，确认"结构一致的对象数组藏在哪个键下面"。常见的 API 响应结构如下：

定位到目标数组后，用 jq 生成 CSV：

jq -r '.data | (map(keys) | add | unique) as $cols
       | $cols, (.[] | [.[$cols[]]]) | @csv' users.json

这个 jq 表达式的逻辑是：收集数组中所有对象出现过的全部键（map(keys) | add | unique）作为 CSV 列头，然后按列头顺序把每个对象的值逐行输出。某个对象缺了某个键不会报错，输出为空单元格。@csv 过滤器会自动给含逗号或换行的值加上双引号，所以贴到 CSV to Markdown 时列不会错位。

第 3 步：用 CSV to Markdown 生成表格

把第 2 步得到的 CSV 文本复制，贴到 CSV to Markdown 里运行。

输出遵循 GFM（GitHub Flavored Markdown）规范，可以直接贴到 GitHub README、Issue、PR 描述、Notion、语雀、飞书等支持 Markdown 的平台。表格的完整语法与格式规则见 Markdown 表格语法。

不同 API 响应结构的转换难度

每个 API 返回的 JSON 结构不同，转 Markdown 表格的难度也不一样。按难度从低到高排列：

拿不准的时候判断标准很简单：先确认能不能切成结构一致的对象数组。结构复杂就用 JSON Formatter 展开看全貌，找到目标键路径。

分页 API 响应合并成一张表

游标或页码方式的分页 API，每一页返回的都是同结构的数组。jq 的 --slurp（-s）选项能把多个 JSON 文件合成一个数组，一次转成一张表。

for page in 1 2 3; do
  curl -s "https://api.example.com/v1/users?page=$page" > "page-$page.json"
done

jq -s '[.[] | .data[]]
       | (map(keys) | add | unique) as $cols
       | $cols, (.[] | [.[$cols[]]]) | @csv' page-*.json

-s 把每个文件的 JSON 包进一个外层数组，[.[] | .data[]] 依次取出每个响应的 data 数组元素，合并成单一数组。后续走同样的 jq 表达式输出一个 CSV，贴到 CSV to Markdown 就得到完整数据的表格。

嵌套 JSON 用"扁平化"处理

用户信息里套了地址对象这种层级 JSON，直接转表格的话，单元格里会塞进 {...} 原文，可读性很差。用点号记法把键名展开成扁平结构：

[
  {
    "id": "usr_001",
    "name": "Mika",
    "address": { "city": "Tokyo", "zip": "100-0001" }
  }
]

原样转的话 address 列会是一整段 JSON 字符串。用 jq 扁平化之后：

jq -r '.[] | {id, name, "address.city": .address.city, "address.zip": .address.zip}
       | [.id, .name, ."address.city", ."address.zip"]
       | @csv' users.json

输出是 id, name, address.city, address.zip 四列的 CSV。贴到 CSV to Markdown 就得到干净的表格。如果字段里是数组（比如 tags: ["a", "b"]），用 join("|") 合成一个字符串放进单元格，表格就不会断。

只靠浏览器安全转换的场景

API 响应里经常带认证 Token、用户个人信息、内部数据库 ID。把这类数据贴到外部转换网站上有泄露风险。FormatArc 的所有转换都在浏览器内运行，不往服务器发数据。判断外部在线工具是否安全，可以参考 在线工具安全检测。

纯浏览器流程：

1. 不用 curl，直接从浏览器 DevTools 的 Network 面板复制 API 响应 JSON。
2. 贴到 JSON Formatter 确认结构和层级。
3. 只保留需要的键，整理成对象数组，拼成 CSV。
4. 贴到 CSV to Markdown 生成最终表格。

数据行数不多的话，不用 jq，光靠浏览器工具组合就够用了。

常见问题与处理

• 响应是单个对象不是数组：用 [ ... ] 包一层变成单行数组，或者转成键值两列的纵向表格。
• 部分对象缺了某个键：jq 的 add | unique 模式会收集所有对象出现过的键作为列头，缺失的值输出为空单元格。
• 值里含管道符 | 或换行：CSV 阶段 @csv 会自动加引号，但贴到 Markdown 表格时管道符要转义成 \|，否则列分隔会乱。表格显示异常时的排查方法见 Markdown 表格不显示或错乱。
• 大整数 ID 精度丢失：64 位整数 ID 如果按数字处理，JavaScript 会四舍五入丢精度。jq 里用 tostring 保持字符串格式更安全。
• 字符乱码：可能是压缩响应或编码不一致，curl 加 --compressed，或者确认 UTF-8 编码后再贴进 Formatter。

总结

• API 响应 JSON 转 Markdown 表格的核心是提取结构一致的对象数组。
• curl 获取响应，jq 把对象数组转成 CSV，再贴到 CSV to Markdown 生成表格，是最稳的路径。
• 分页响应用 jq 的 --slurp（-s）合并，嵌套对象用点号记法扁平化。
• FormatArc 所有转换在浏览器内完成，带敏感数据的 API 响应也能安全处理。

参考

• RFC 8259: The JavaScript Object Notation (JSON) Data Interchange Format在新标签页中打开
• GitHub Flavored Markdown Spec — Tables (extension)在新标签页中打开
• jq Manual在新标签页中打开