API レスポンスの JSON を Markdown 表にする — curl から README まで

API レスポンスを README や Issue、社内 Wiki に貼り付けるとき、JSON の生データのままでは読みにくいので Markdown テーブルにしたい場面はよくあります。この記事では、curl で取ってきた JSON をブラウザだけで Markdown 表に変換する手順を、ページネーション・ネスト・配列以外のレスポンスといった現場で詰まるケースまで含めて整理します。

API レスポンスを Markdown 表にする最短ルートは「curl で取得 → jq で配列を切り出す → CSV を経由 → CSV to Markdown で表化」です。配列以外のレスポンスは jq で対象配列に降りるか、[ ... ] で包んでから処理します。すべてブラウザ内で完結するので、認証ヘッダー付きのレスポンスでも外部に送信されません。

結論: 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/ja/json-formatter/

# 3. data 配列だけ取り出して CSV を組み立てる
jq -r '.data | (map(keys) | add | unique) as $cols
       | $cols, (.[] | [.[$cols[]]]) | @csv' users.json

# 4. 出力された CSV を CSV to Markdown に貼って Markdown 表を生成
#    https://formatarc.com/ja/csv-to-markdown/

curl の組み立てやレスポンスが読みづらいときの整形については curl の JSON を整形する 4 つの方法 で詳しく扱っています。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 整形ガイド を参照してください。

ステップ 2: 配列を切り出して CSV を作る

整形済み JSON を眺めて、「どのキーの下に同じ形のオブジェクトの配列があるか」を特定します。代表的なパターンは次のとおりです。

該当する配列を .data のように指定し、続けて CSV を組み立てます。

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

この jq 式は、配列内の全オブジェクトから登場するキーを集めて列ヘッダーにし、各行を同じ順で並べます。一部のオブジェクトに欠けているキーがあっても、空セルとして埋まります。@csv は値にカンマや改行が含まれる場合に自動で "..." でエスケープしてくれるので、CSV を CSV to Markdown に貼り付けたときに崩れません。

ステップ 3: CSV to Markdown で表に変換する

ステップ 2 で得た CSV を CSV to Markdown に貼り付けて変換します。

出力は GFM（GitHub Flavored Markdown）互換のテーブルなので、README、Issue、Notion、Slack の Markdown 入力にそのまま貼れます。表の体裁を整えたい場合の細かな書き方は Markdown 表の書き方 で扱っています。

API レスポンスのパターン別 変換難度

API ごとに JSON の形が違うので、Markdown 表にしやすいかどうかも変わります。代表的なパターンを難度順に並べました。

迷ったときの判断基準はシンプルです。「同じキーを持つオブジェクトの配列に切り出せるか」を最初に確認し、切り出せないなら JSON Formatter で構造を見直して、どのキーパスに降りればよいか確認します。

ページネーション付きの API を 1 つの表にまとめる

カーソル方式やページ番号方式の API は、ページごとに同じ形の配列を返します。jq の --slurp（-s）で複数レスポンスを 1 つの配列にまとめると、同じ手順で表にできます。

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 の 4 列の CSV になります。これを CSV to Markdown に貼れば、ネストが入った API レスポンスもそのまま表にできます。配列を含むネスト（tags: ["a", "b"] のようなケース）は join("|") などで 1 セルにまとめると崩れません。

ブラウザだけで完結させたいとき

API のレスポンスに認証ヘッダーや個人情報が含まれることが多いため、外部の変換サイトに丸ごと貼るのは現実には選びにくい選択肢です。FormatArc の変換処理はすべてブラウザ内で行われ、入力をサーバーへ送信しません。詳しい仕組みと第三者ツールとの比較は オンライン変換ツールの安全性 を参照してください。

ブラウザだけで完結させる手順は次のとおりです。

1. curl の代わりにブラウザの DevTools（Network タブ）でレスポンスをコピー
2. JSON Formatter に貼って構造を確認
3. 必要なキーだけを残した配列を作り、CSV にコピペで整える
4. CSV to Markdown で Markdown 表を生成

jq が手元にない環境でも、構造が小さい配列なら手作業の CSV 化でも十分実用になります。

よくあるつまずきと対処

API レスポンスを表にしようとして詰まる典型例をまとめます。

• レスポンスがオブジェクトの単体: [ ... ] で配列に包むか、キーと値の 2 列表に組み替える。詳しくは JSON を Markdown テーブルに変換する方法 を参照
• 一部のオブジェクトにキーが欠けている: jq の add | unique パターンで全キーを集めるか、空セル "" を許容する
• 値に改行やパイプ | が含まれている: CSV にした時点で @csv がクォートしてくれますが、Markdown 表に貼る段階でパイプは \| にエスケープが必要です。詳しくは Markdown 表が表示されないときの対処 を参照
• 数値の精度が落ちる: Number 型がまるめられる API（ID など）は、jq で tostring を挟むと文字列として保てます
• 文字コードが化ける: curl --compressed を付けるか、iconv -f UTF-8 で揃えてから JSON Formatter に貼る

関連する変換ガイド

• curl の JSON を整形する 4 つの方法 — jq / Python / FormatArc / ブラウザでの整形手順を比較
• JSON を Markdown テーブルに変換する方法 — API 由来でない JSON 全般を表化するときの基本
• CSV を Markdown テーブルに変換する方法 — CSV を中間表現にする利点と落とし穴
• JSON 整形のコツ — 配列の整理やキーソートで構造を読みやすくする

参考

• RFC 8259: The JavaScript Object Notation (JSON) Data Interchange Format
• GitHub Flavored Markdown Spec — Tables (extension)
• jq Manual