OpenAPI GeneratorでTypeScript APIクライアントを生成する｜Vue 3連携

※ 当ブログ「日々是事始め（コレコト）」はプロモーションを含みます。

前の記事で「OpenAPI ファイルは API の設計図」だと整理しました。ここからが面白いところで、その設計図（openapi.yaml）から TypeScript の型と API 呼び出しコードを自動生成できます。手書きの fetch を卒業し、存在しないフィールドを書くと即エラーになる「型安全」な呼び出しに進みます。この記事では typescript-axios ジェネレーターを使います。

※ 学習用に調べた内容を個人的にまとめたものです。文章は AI の補助を受けて作成しています。

生成までの流れ
生成コマンド
生成コードを Vue から呼ぶ
生成コードは「手で編集しない」
もっと体系的に学ぶなら（書籍）
次に読む

生成までの流れ

openapi.yaml
   │  OpenAPI Generator（typescript-axios）
   ▼
src/generated/api/
   ├─ api.ts            … listTasks() などの関数と Task などの型
   ├─ configuration.ts  … 接続設定（basePath など）
   └─ base.ts など      … 共通コード
   │
   ▼
Vue から import して呼ぶ

生成コマンド

npm スクリプトにしておくと、仕様が変わるたびに叩き直せます。@openapitools/openapi-generator-cli を使う例です（実行には Java が必要です）。

npm i -D @openapitools/openapi-generator-cli

// package.json
{
  "scripts": {
    "gen:api": "openapi-generator-cli generate -i openapi/openapi.yaml -g typescript-axios -o src/generated/api"
  }
}

npm run gen:api

生成コードを Vue から呼ぶ

生成された TasksApi を使って一覧を取得します。Task 型も生成物から import できます。

<script setup lang="ts">
import { ref, onMounted } from 'vue'
import { TasksApi, Configuration } from '@/generated/api'
import type { Task } from '@/generated/api'

const api = new TasksApi(
  new Configuration({ basePath: import.meta.env.VITE_API_BASE_URL })
)

const tasks = ref<Task[]>([])

onMounted(async () => {
  const res = await api.listTasks()
  tasks.value = res.data   // res.data は Task[] に型付けされている
})
</script>

res.data が Task[] として型付けされているので、t.titel のようなタイプミスはコンパイル時に弾かれます。これが手書き fetch との決定的な差です。

生成コードは「手で編集しない」

重要

src/generated/api/ 配下は原則として手で編集しません。再生成で上書きされて消えるからです。.gitignore に入れて生成物はコミットしない運用もよくあります。

「編集したくなったら、生成物を直接いじるのではなく、その外側にラッパー（repository層）を作る」――これが保守を楽にするコツです。生成物を .vue から直接呼ぶのも避けたほうがよく、その理由と設計は別記事で扱います。なお、より実務寄り・キャッシュ込みで扱いたい場合は Orval という選択肢もあります。