Next.js初心者がまず「型」を理解して、次にOpenAPIで自動化するまで

Next.js + TypeScript を勉強していると、ネットで「OpenAPIで型を自動生成しよう」みたいな記事を見かけます。便利そう。でも、いきなり真似すると、たぶんこうなります。

「コマンド叩いたら型ができた…けど、これ何が起きてるの？」

これは結構もったいないです。型がそもそも何なのかを理解しないまま自動生成に飛びつくと、生成された型を使いこなせないからです。

そこでこの記事は、次の3ステップで進みます。急がば回れです。

OpenTask(Next.js + TypeScript + Rails API)という個人開発アプリの実コードを使いながら、初心者目線で順番に説明します。

STEP 1：まず「型」を理解する

🎯 このステップのゴール：型が「データの形の約束」だと腹落ちする

型がないと、何が困るのか

まず TypeScript の「型」がない世界を見てみましょう。APIからTodoの一覧を取ってきて、画面に出すコードです。

// 型なし(ただのJavaScript)
const todos = await fetchTodos();

todos.map((todo) => {
  console.log(todo.titel); // ← タイプミス。でも誰も怒ってくれない
});

title を titel と打ち間違えていますが、JavaScript は何も言いません。実行して画面が真っ白になって、初めて「あ、スペル間違えた」と気づきます。コードを書いている時点では、間違いに気づけない。 これが型なしの世界のつらさです。

APIレスポンスに「型」を付けてみる

そこで「このデータはこういう形をしているよ」と宣言するのが型です。Todoの形を、まずは手で書いてみましょう。

// Todoはこういう形をしている、という宣言
type Todo = {
  public_id: string;
  title: string;
  completed: boolean;
};

これを使うと、さっきのコードはこう変わります。

const todos: Todo[] = await fetchTodos();

todos.map((todo) => {
  console.log(todo.titel);
  //                ^^^^^ ← エディタが即座に赤線で警告！
  //          「Todoに titel なんてプロパティ無いよ」
});

実行する前に、エディタが間違いを教えてくれます。さらに todo. と打った瞬間に public_id / title / completed が補完候補に出てきます。これが型のいちばんの嬉しさです。

型は「自分とコードの約束」

ここで一番大事な感覚をつかんでください。型とは、

「このデータには、こういうフィールドが、こういう種類で入っている」という約束

です。約束があるから、エディタは補完を出せるし、約束を破ったコード(titel)を見つけて警告できる。型を理解する = この"約束"の感覚を持つことだと思ってください。

ここまでで、型が何のためにあるかは腹落ちしたはずです。次のステップに進みましょう。

STEP 2：手書きの型は、いつか嘘をつく

🎯 このステップのゴール：なぜ手書きの型は壊れるのか、を知る

STEP 1 で書いた Todo 型は、手で書いたコピーです。本物のAPIとは別の場所に存在しています。

バックエンドのAPI(本物)        自分が手書きした型(コピー)
   completed: true       ⇄       completed: boolean

最初は一致しています。でも開発が進むと、バックエンド側でこんな変化が起きます。

• フィールドの名前が変わる

• 新しいフィールドが増える

• null が返るようになる

そのたびに、手書きのコピーは古いまま取り残されます。 しかも厄介なのは、型としては正しいのでエラーにならないことです。

// APIは completed をやめたのに、手書きの型には残っている
console.log(todo.completed); // 型エラーは出ない → でも実行すると undefined

「型があるのにバグる」のは、たいていこれが原因です。

STEP 2 の結論：型は便利。でも手で書き写したコピーは、本物のAPIと必ずいつかズレる。

STEP 3：OpenAPIのようなもので「自動化」する

🎯 このステップのゴール：設計図から型を生成し、常にAPIと一致させる

STEP 1 で型を理解し、STEP 2 で手書きの限界が分かりました。ここで初めて、自動化の出番です。

考え方はシンプルです。型を手で書き写すからズレる。なら、APIの定義から機械的に作ればいい。

① APIの「設計図」を一枚用意する

そのために、APIがどんなデータを返すかを機械が読める形で書いた設計図を用意します。それが OpenAPI です(YAMLで書く、APIの仕様書だと思ってください)。

# openapi/openapi.yaml ―― これがAPIの"正解"になる
Todo:
  type: object
  properties:
    public_id:
      type: string
    title:
      type: string
    completed:
      type: boolean

見てのとおり、STEP 1 で手書きした Todo 型と、言っていることは同じです。違うのは、これが「機械が読める設計図」だという点だけ。

② 設計図から型を生成する

OpenTask では openapi-typescript というツールで、この設計図からTypeScriptの型を生成します。

// frontend/package.json
"scripts": {
  "generate:api-types": "openapi-typescript ../openapi/openapi.yaml -o src/types/api/schema.ts"
}

pnpm generate:api-types

これで src/types/api/schema.ts に、設計図と完全に一致した型が自動で書き出されます。このファイルは手で触りません。 APIが変わったら、また同じコマンドを叩くだけ。

生成された型から、使いやすい Todo 型を取り出します。

// frontend/src/lib/api/todos.ts
import type { paths } from "@/types/api/schema";

// /api/v1/todos のGETレスポンスの、配列1個ぶんの型
export type Todo =
  paths["/api/v1/todos"]["get"]["responses"]["200"]["content"]["application/json"][number];

STEP 1 で type Todo = {...} と手書きしたものが、設計図から自動で出てくるようになりました。やっていることは同じ。でも、もう手で書き写していません。

③ 自動化のいちばんの効果

ここで STEP 2 の問題を思い出してください。APIが completed をやめたら、設計図を直して再生成します。すると Todo 型から completed が消え…

<span>{todo.completed ? "完了" : "未完了"}</span>
//          ^^^^^^^^^ ← TypeScriptが即エラー！

画面を開く前に、コンパイルの時点で「ここ直してないよ」と教えてくれます。 手書きでは気づけなかった変更に、自動生成なら必ず気づけます。

【手書き】 API変更 → 型は古いまま → 実行して初めてバグ発覚 😱
【自動生成】 API変更 → 再生成 → コンパイルエラーで即気づく 😎

まとめ：なぜ「まず型を理解する」順番が大事なのか

最後に、この記事をこの順番で書いた理由を。

自動生成された paths["/api/v1/todos"]...[number] という呪文みたいな型も、STEP 1 で「型とは約束だ」と理解していれば、「ああ、Todo一覧の1個ぶんの型を取り出してるんだな」とちゃんと読めます。逆に、型を理解しないまま自動生成だけ真似すると、生成された型が壊れたとき何も対処できません。

• STEP 1：型は「データの形の約束」。補完が効き、間違いを実行前に見つけてくれる

• STEP 2：手で書き写した型は、本物のAPIとズレて静かに嘘をつく

• STEP 3：OpenAPI の設計図から自動生成すれば、型は常にAPIと一致する

正直、最初は設計図を書く手間が増えて「面倒だな」と感じます。私もそうでした。 でも、型の意味をちゃんと理解した上で自動化に進むと、その便利さを心から実感できます。

Next.jsの勉強で型に慣れてきたら、次のステップとして、ぜひ OpenAPI での自動生成を試してみてください。

参考

この記事で使ったコードは、すべて以下のリポジトリで公開しています。実際の openapi.yaml や生成設定、SWRフックの全体像はこちらを見てください。

• OpenTask(本記事のサンプルアプリ) … https://github.com/Kazuya-Sakashita/opentask

  • APIの設計図：openapi/openapi.yaml

  • 型生成のコマンド：frontend/package.json

  • 生成した型の使い方：frontend/src/lib/api/todos.ts

関連ドキュメント

• openapi-typescript 公式ドキュメント … 本記事で使った型生成ツール

• OpenAPI Specification … APIの設計図の仕様

• SWR 公式ドキュメント … 生成した型と組み合わせたデータ取得