JSONスキーマテンプレートでAPIペイロードを標準化する方法

君もAPI叩いてる？JSONと戦ってる？仕様で口論したことある？

エンジニアならきっと、JSONに心を折られたことがある。しかも一度じゃない。何度も。ええ、何度もです。

始まりはいつも静かだ。
Postmanを開き、セブンで買った缶コーヒーをひと口。
「さて、Sendっと……」

「……ん？dataがdatasになってる？？誰だよ複数形教えたやつ」
「pageSize？うちのプロジェクトはlimit統一って言ったよね？」
「え、これ成功レスポンスでnull返してるけど！？マジで！？」

ようこそ、インテグレーション地獄へ。
人口：君、混乱するチームメイト、そして今死んだ君の忍耐。

しかも一番厄介なのは、APIのロジックじゃない。
レスポンスの形（payload shape）が戦犯なんだよ。

そして、絶望の中で君はそっとこうつぶやく。

「……てか、うちのAPIってスキーマあるんだっけ？」

あるんだよ。
ただ、誰も書いてないだけ。
そして、もっと最悪なのは——誰も使い回してない。

スキーマ。それは最初のAPIから君を悩ませてきた亡霊。

JSON Schemaとは何か？それはAPI界のパスポート＆保安検査場みたいなもの。

チームにこう伝える役目がある：

• 何のデータが来るのか
• どんな型が許されるのか
• 必須項目とオプションは何か

さらに、ドキュメントを自動生成したり、テストデータを用意したり、Mock APIも作れる。
本来なら、最高の相棒になるべき存在。

でも現場では？
スキーマはまるで誰も開けたくない謎の引き出し。

心当たりあるだろ？

• みんな毎回同じ構造を再定義
• バックエンドが無言で仕様変更
• フロントは勝手に“察する”
• QAが「レスポンス不一致」でJiraに47件チケット投下

あるあるすぎて、笑えない。

この悪循環を、ここらで断ち切ろう。
一度定義すれば、永遠に使いまわせるスキーマ、そしてEchoAPIという頼れる相棒の話をしよう。

スキーマは人生。再定義地獄から君を救うリスト

以下はAPI界の常連メンバー。再利用スコア付きでご紹介：

定義しなければ、野に放たれたJSONは突然変異を起こす。
定義すれば、統一された美しい世界が広がる。

1. API共通レスポンス：みんな使ってるけど、誰も明文化してない

{
  "code": 0,
  "message": "OK",
  "data": {}
}

これはまるでAPI界の白ごはん。
どのエンドポイントでも出てくる。でも、繰り返すと味気ない。

この構造、27ファイルにコピペする前に、スキーマにしよう：

{
  "type": "object",
  "properties": {
    "code": { "type": "integer" },
    "message": { "type": "string" },
    "data": {}
  },
  "required": ["code", "message", "data"]
}

EchoAPIではこれを BaseResponse に登録。
他のレスポンス？それを拡張すればいいだけ。
もう200レスポンスでdata: nullなんて驚き、ないから。

2. ページネーション：API界の肉体労働者

商品一覧、検索結果、コメント一覧、管理画面。
どこにでもいるのが、こいつ：

{
  "items": [],
  "page": 1,
  "pageSize": 20,
  "total": 182
}

でもチームによって違うんだ。
limit, perPage, totalCount……誰か統一してくれ！！

これが正義：

{
  "type": "object",
  "properties": {
    "items": {
      "type": "array",
      "items": {}
    },
    "page": { "type": "integer" },
    "pageSize": { "type": "integer" },
    "total": { "type": "integer" }
  },
  "required": ["items", "page", "pageSize", "total"]
}

EchoAPIではこれをテンプレート化して Paginated<T> にする。
items の中身を User とかにすれば、即完成。
AIより賢く、幻覚も見ない。

3. エンティティモデル：見慣れすぎて顔も見たくない

{
  "id": 1,
  "username": "alice",
  "email": "alice@example.com",
  "role": "admin"
}

これ、9箇所で使ってたら？
誰かが role を userRole に変えた瞬間——
9つのエンドポイントが爆発。怒号飛び交うSlackチャンネル。

解決策？「繰り返すな。再利用せよ。」

{
  "type": "object",
  "properties": {
    "id": { "type": "integer" },
    "username": { "type": "string" },
    "email": { "type": "string", "format": "email" },
    "role": { "type": "string", "enum": ["admin", "user", "guest"] }
  },
  "required": ["id", "username"]
}

これを UserSchema として保存。ログイン、会員登録、ユーザー一覧、全部これでOK。
変更は1箇所、EchoAPIが全部反映。
もはや脳みそ付き契約書。

4. フィールドフラグメント：小さな部品、大きな力

id, createdAt, updatedAt, status
毎回書くの、正直だるい。

なら分割しよう。レゴブロックのように：

{
  "createdAt": {
    "type": "string",
    "format": "date-time",
    "description": "作成日時"
  }
}

これを User, Product, Invoice などに組み込むだけ。
部品として再利用できるから、管理も楽。
エンジニア心をくすぐる、「クリックして組み立て」な体験。

EchoAPI：JSONスキーマ界の建築士 & セラピスト

手書きのスキーマ？それは、説明書のないIKEA家具の組み立て。

でもEchoAPIなら：

JSONやSQLからインポート

既存レスポンスを数分で構造化スキーマに！
レガシーAPIや謎仕様のDB、全部コピペでOK。タイプ付きに変換してくれるから、ドキュメント化も一発。

ドラッグ＆ドロップでスキーマ作成

UIで設計、JSONは勝手に生成。
直感的な画面で設計できるから、JSONの構文ミスとはおさらば。

AIによるスキーマ強化

EchoAPIはただのバリデータじゃない。
説明文を補完し、例を自動生成し、誰が見てもわかるスキーマに変えてくれる。
まさに補助輪付きのスキーマ設計。

モジュール＆再利用可能なスキーマ

部品化したスキーマで一括管理！
User、Product、Paginated など、一度定義すれば全プロジェクトで使える。
一か所変えれば全部に反映。夢のような同期。

VSCodeプラグイン対応

エディタの外に出る必要なし。
リアルタイムでスキーマをプレビュー＆編集。
チーム全体と連携しながら、IDEの中で完結。

それはまるで、NotionのようなAPI管理。
Figmaのようなスキーマ設計。
そして——Jiraで唯一、開くのが楽しいチケット。

スキーマを使えば、夜もぐっすり眠れる

• JSON Schemaはデータ契約。 Slackで口論するくらいなら、スキーマ見せよう。
• 再利用スキーマは工数削減の神。 コピペ地獄からの脱出。
• EchoAPIは、手書きスキーマを美しく、共同作業可能な設計図に変える。
• 仕様争いは終わる。 だって、みんな同じスキーマ見てるから。

スキーマなしでAPIを書くのは、ゼリーの上にビル建てるようなもの。
毎回同じ構造を再定義するのは、おばあちゃんがりんご1個のために毎回買い物リストを新しく書くようなもん。

だから——未来の自分のために。
EchoAPIを開こう。
君の構造、スキーマ化しよう。
混沌に秩序を。
そして——もうdataとdatasで揉めるの、やめよう。

EchoAPIで作ったプロジェクトは、ただ「動く」だけじゃない。
整ってるんだよ。

スキーマがビシッと立てば、コードはグングン走る。