API連携の実装では、レスポンス例を見ながら「このフィールドは必須なのか」「配列の中身は何型なのか」「画面側ではどこまで信用してよいのか」を確認する時間がよく発生します。

ドキュメントに型が書かれていても、実際のレスポンスには null が混ざっていたり、配列が空だったり、環境によって追加フィールドが返ってきたりします。そこでこの記事では、DevToolKits のツールを使って、JSON レスポンスを実装に使える形へ整える流れを紹介します。

こんな場面で使う

たとえば、外部 API からユーザー情報を取得する実装をしているとします。

{
  "id": 42,
  "name": "Ada Lovelace",
  "email": "ada@example.com",
  "roles": ["admin", "editor"],
  "profile": {
    "timezone": "Asia/Tokyo",
    "company": null
  }
}

このレスポンスをそのまま見て実装を始めることもできますが、少し複雑になると手作業の判断が増えます。

  • company は string | null なのか
  • roles は文字列配列で固定してよいのか
  • 画面側で使う型定義をどこに置くか
  • ランタイムでも検証する必要があるか

こういう確認を、ツールをつないで短くします。

1. JSONを整形して構造を読む

まず JSON整形ツール にレスポンスを貼り付けます。

この段階で見るポイントは、きれいに表示することだけではありません。実装前に、次のような違和感を拾います。

  • ネストが深すぎる場所
  • null が混ざるフィールド
  • 数値に見えるけれど文字列で返る値
  • 空配列になりやすそうな値
  • APIドキュメントにない追加フィールド

JSONを整えるだけでも、レビュー時に「どのレスポンスを前提にしたか」を共有しやすくなります。

2. TypeScript型を作る

構造が見えたら、同じ JSON を JSON to TypeScript に貼り付けます。

出力例は次のようになります。

export interface UserResponse {
  id: number;
  name: string;
  email: string;
  roles: string[];
  profile: Profile;
}

export interface Profile {
  timezone: string;
  company: null;
}

ここで大事なのは、生成結果をそのまま正解にしないことです。生成された型は「貼り付けたサンプルから推測した型」です。実際には company が会社名を持つケースもあるなら、プロジェクト側では次のように調整します。

export interface Profile {
  timezone: string;
  company: string | null;
}

ツールは、型定義のたたき台を作るために使います。最後の判断は、API仕様や実データを見て行います。

3. 必要ならZodスキーマも作る

外部 API のレスポンスを画面や保存処理で使う場合は、TypeScript型だけでは足りないことがあります。TypeScript はコンパイル時の助けにはなりますが、実行時に届いたデータを検証してくれるわけではありません。

そこで、同じ JSON を JSON to Zod に貼り付けます。

生成されたスキーマをもとに、実際の仕様に合わせて調整します。

import { z } from "zod";

export const UserResponseSchema = z.object({
  id: z.number(),
  name: z.string(),
  email: z.string().email(),
  roles: z.array(z.string()),
  profile: z.object({
    timezone: z.string(),
    company: z.string().nullable(),
  }),
});

export type UserResponse = z.infer<typeof UserResponseSchema>;

こうしておくと、APIレスポンスを受け取った直後に UserResponseSchema.parse(data) や safeParse(data) で検証できます。

4. 実装に入れる前に確認すること

型とスキーマができたら、実装前に次の点を見直します。

  • サンプルが1件だけではないか
  • エラー時のレスポンスも確認したか
  • null と未定義を区別できているか
  • 日付や金額が文字列で返る可能性はないか
  • 個人情報やトークンをツールに貼っていないか

DevToolKits の各ツールはブラウザ上で使う前提ですが、実務ではサンプルを扱う時点で機密情報をマスクしておくのが安全です。

まとめ

APIレスポンスから実装に入るときは、いきなりコードを書き始めるより、次の順番にすると手戻りが減ります。

  1. JSON整形で構造を読む
  2. JSON to TypeScriptで型のたたき台を作る
  3. JSON to Zodで実行時検証を足す
  4. 実データと仕様を見て人間が調整する

この流れにしておくと、API連携の実装、レビュー、仕様確認がかなり進めやすくなります。