FormatArc JSON Formatter 中整理後的 API 回應結果FormatArc JSON Formatter 中整理後的 API 回應結果
作者: FormatArc 編輯部發布日期: 2026-09-02更新日期: 2026-09-02

JSON API 回應表格化：curl、jq、分頁合併、6 種回應型別

要在 GitHub README、Issue、HackMD 或 Notion 中分享 API 回應的資料時，直接貼上原始的 JSON 往往讓讀者難以快速掌握重點。把資料整理成 Markdown 表格會清楚得多。這篇整理從 curl 取得 JSON 到產生 Markdown 表格的完整流程，包含分頁（Pagination）、巢狀物件、回應不是陣列等實務上常遇到的狀況。，直接貼上原始的 JSON 往往讓讀者難以快速掌握重點。把資料整理成 Markdown 表格會清楚得多。這篇整理從 curl 取得 JSON 到產生 Markdown 表格的完整流程，包含分頁（Pagination）、巢狀物件、回應不是陣列等實務上常遇到的狀況。

最短路徑是「curl 取得回應 → jq 擷取陣列 → 轉為 CSV → CSV 轉 Markdown 產生表格」。回應若不是陣列，先用 jq 定位到目標陣列，或用 [ ... ] 包起來再處理。所有轉換都在瀏覽器內完成，包含認證標頭（Authorization Bearer）的回應也不會傳送到外部伺服器。

結論：API 回應要「擷取陣列」才能表格化

API 回應的 JSON 能不能變成表格，關鍵在於「能不能擷取出一組結構相同的物件陣列」。實際上的 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-tw/json-formatter/

# 3. 只擷取 data 陣列並組建 CSV
jq -r '.data | (map(keys) | add | unique) as $cols
       | $cols, (.[] | [.[$cols[]]]) | @csv' users.json

# 4. 將輸出的 CSV 貼到 CSV 轉 Markdown 產生表格
#    https://formatarc.com/zh-tw/csv-to-markdown/

如果不想安裝 jq，也可以先把 JSON 貼到 JSON Formatter 確認結構和鍵名，再決定下一步。

第 1 步：取得並整理 API 回應

如果是瀏覽器能直接開啟的 GET 端點，把回應複製貼到 JSON Formatter 就能快速整理。用 curl 時，-s 可以隱藏進度顯示，需要認證時用 -H 加入標頭。

將回應存成檔案後，你可以反覆修改 jq 的篩選條件直到輸出滿意為止。

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 的環境下最快的格式化手段。更多 curl 搭配 JSON 的格式化方法可參考 curl JSON 格式化的 4 種方法。

第 2 步：擷取陣列並產生 CSV

確認格式化後的 JSON，找出「結構相同的物件陣列在哪個鍵路徑下」。常見的 API 回應結構如下：

API 回應結構表格目標陣列位置jq 擷取式
[ {...}, {...} ]（最上層為陣列）最上層.
{ "data": [ ... ] }data.data
{ "items": [ ... ], "next": "..." }items.items
{ "results": { "users": [ ... ] } }results.users.results.users

確認目標陣列路徑後，執行以下 jq 命令產生 CSV：

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

這個 jq 式會收集陣列內所有物件出現的鍵作為 CSV 欄位標頭（$cols），並依相同順序輸出每個物件的值。若某些物件缺少特定鍵，會以空白儲存格填入而不會報錯。@csv 過濾器會自動處理值中包含逗號或換行符號的情況，加上引號包裹，貼到 CSV 轉 Markdown 時欄位不會跑位。

第 3 步：CSV 轉 Markdown 表格

將第 2 步得到的 CSV 文字複製到 CSV 轉 Markdown 工具並執行轉換。

CSV 轉 Markdown 工具產生由 API 回應構成的表格CSV 轉 Markdown 工具產生由 API 回應構成的表格

輸出遵循 GFM（GitHub Flavored Markdown）標準，可以直接貼到 GitHub README、Issue、HackMD、Notion、Obsidian 或 Slack 等支援 Markdown 的平台。表格語法的對齊、換行與轉義規則詳見 Markdown 表格語法總整理。

依 API 回應型別判斷轉換難度

每個 API 回傳的 JSON 結構不同，表格化的難度也因此有差異。以下列出常見型別：

API 型別回應結構轉換難度處理要點
簡單 List API[ { ... } ] 平坦陣列低. 直接傳入
包裝的集合{ "data": [ { ... } ] }低用 .data 進入目標陣列
分頁 API{ "items": [ ... ], "next_cursor": "..." }中逐頁用 jq 合併後再擷取
巢狀物件{ "user": { "name": ... }, "stats": { ... } }中以點號記法（dot notation）建立鍵名來扁平化
GraphQL 回應{ "data": { "users": { "edges": [ { "node": { ... } } ] } } }高用 .data.users.edges[].node 擷取節點陣列
異質物件混合陣列[ { type: "A", ... }, { type: "B", ... } ]高依 type 過濾後分別建立表格

拿不準時的判斷標準很簡單：先確認「能不能擷取出結構相同的物件陣列」，如果不行就用 JSON Formatter 展開整體結構，找到正確的路徑。

分頁 API 回應合併成一個表格

使用游標（Cursor）或頁碼（Page number）方式分頁的 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 轉 Markdown 產出完整表格。

巢狀 JSON 用「扁平化」處理

使用者資料中包含地址物件這類巢狀結構，如果直接轉表格，特定儲存格會原封不動地顯示 {...} JSON 文字，可讀性很差。用點號記法建立新的鍵名來扁平化：

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

維持這個結構直接轉，address 欄會顯示原始物件字串。用 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 轉 Markdown 就能把巢狀結構的 API 回應變成乾淨的表格。如果包含陣列欄（例如 tags: ["a", "b"]），用 join("|") 等手法把它們合併成單一儲存格內的字串，表格就不會斷裂。

想完全在瀏覽器內完成時

API 回應中常包含認證標頭、使用者個人資料或內部資料庫的識別碼。把這些資料貼到外部轉換網站有資安與個資外洩的風險。使用前可參考 線上轉換工具使用前必做的 5 項隱私檢查。FormatArc 的所有轉換處理都在瀏覽器內執行，不會將輸入傳送至伺服器。

完全使用瀏覽器的步驟如下：

  1. 用瀏覽器開發者工具（DevTools）的 Network 分頁複製 API 回應，代替 curl
  2. 貼到 JSON Formatter 確認結構與層級
  3. 只保留需要的鍵，整理成陣列並組建為 CSV
  4. 貼到 CSV 轉 Markdown 產出最終的 Markdown 表格

如果資料行數不多，即使沒有 jq，手動整理 CSV 也完全實用。

常見問題與對策

把 API 回應表格化時容易卡住的情況：

  • 回應是單一物件而非陣列：用 [ ... ] 包成一行陣列，或改組建「鍵／值」兩欄的直式表格
  • 部分物件缺少特定鍵：jq 的 add | unique 模式會收集所有物件中出現的鍵作為標頭，缺失的值以空白儲存格（""）填入
  • 值包含換行或管線符號（|）：CSV 階段 @csv 會自動加引號，但貼到 Markdown 表格時管線符號需要轉義為 \|，否則欄位會斷裂。其他表格斷裂症狀與修正方法見 Markdown 表格語法錯誤診斷。
  • 大數整數 ID 精度喪失：64 位元整數 ID 若以數字型別處理，在 JavaScript 中會因精度限制被四捨五入。用 jq 的 tostring 轉為字串即可避免
  • 字元亂碼：可能是回應使用了壓縮編碼或字元集不匹配。加上 curl --compressed，或用 iconv -f UTF-8 統一編碼後再貼到 JSON Formatter

常見問題

API 回應不是陣列而是單一物件時，怎麼表格化？

如果回應是 { "id": 1, "name": "Alice" } 這種單一物件，有兩種做法。第一種：用 [{ ... }] 包起來變成一列一行的橫式表格。第二種：組建「屬性（Key）／值（Value）」兩欄的直式表格。單一物件的設定值或詳細資料用直式表格可讀性更好。

不裝 jq 能在瀏覽器直接轉嗎？

可以。從瀏覽器開發者工具複製 JSON，貼到 JSON Formatter 確認結構後，挑出需要的物件陣列，整理成 CSV 格式，再貼到 CSV 轉 Markdown 即可。資料量小的時候不需要任何 CLI 工具。

回應中包含認證標頭或個資，能用線上工具嗎？

一般會把資料上傳到伺服器的線上轉換網站不建議使用。FormatArc 的轉換邏輯完全在瀏覽器的 Client-side 執行，輸入資料不會傳送到任何伺服器，包含認證標頭或內部資料的 API 回應也可以安全處理。

大量 API 回應也能表格化嗎？

Markdown 表格本身是文字格式，數百行以內渲染沒有問題，但超過數千行時 GitHub 或渲染器的載入速度會下降。大量資料建議在 jq 中用 .[:50] 只截取前 50 到 100 行作為示例表格，完整資料則以 CSV 或 JSON 檔案連結的方式附上。

重點整理

  • API 回應 JSON 表格化的核心是「擷取結構相同的物件陣列」
  • 用 curl 取得、jq 組建 CSV、再傳到 CSV 轉 Markdown 是最穩定的路徑
  • 分頁回應用 jq 的 --slurp（-s）合併，巢狀物件用點號記法扁平化
  • FormatArc 所有轉換都在瀏覽器內執行，敏感的 API 回應資料也可以安全處理

參考