Zenn
😎

Vue × OpenAPI × TypeScriptで安全なAPI通信を実現する構成

に公開
TypeScript
Vue.js
Swagger
axios
OpenAPI
tech

フロントエンドからバックエンドAPIを呼び出すとき、以下のような課題に直面したことはありませんか？

  • APIの型定義がズレる
  • エンドポイント名のスペルミスに気づかない
  • バリデーションエラーの扱いが一貫しない

これらを一気に解決するのが、OpenAPI（Swagger）とTypeScriptの自動コード生成です。
本記事では、Vue 3 + Vite + TypeScript 環境で、OpenAPIを活用して安全・型安全・再利用可能なAPI通信を実現する構成を紹介します。

📦 技術構成

項目 使用技術
フレームワーク Vue 3 (Composition API)
型生成 @hey-api/openapi-ts
API仕様管理 OpenAPI 3.0 (YAML)
API通信 Axios + 型付き関数自動生成

✅ OpenAPIスキーマの準備

まずは、バックエンドで OpenAPI定義（swagger.json / yaml） を用意します。

paths:
  /users:
    get:
      operationId: getUsers
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/User'
components:
  schemas:
    User:
      type: object
      properties:
        id:
          type: string
        name:
          type: string

🔧 型生成：openapi-ts を使ってTypeScriptコードを自動生成

npx @hey-api/openapi-ts openapi.yml -o src/api/

このコマンドで、以下のような型付きコードが自動生成されます：

export type User = {
  id: string;
  name: string;
};

export async function getUsers(): Promise<User[]> {
  return axios.get('/users');
}

💡 API呼び出しを使う側はこうなる

<script setup lang="ts">
import { getUsers } from '@/api';

const users = ref<User[]>([]);

onMounted(async () => {
  users.value = await getUsers();
});
</script>
  • 型補完が効く
  • レスポンス型の保証
  • エンドポイント名・パラメータミスを事前に検出できる

⚠️ よくある落とし穴と対策

問題 対策
スキーマが更新されたらコードがズレる 毎回CIで自動再生成する or watch化する
Axiosの設定を統一したい 共通 axiosInstance をラップして export する
サーバーの errorCode を型で扱いたい x-error-code など独自拡張とマッピング戦略を採用

🧪 補足：インターセプターの活用

  • このようにインターセプターを活用することで、APIごとの try-catch を省略しつつ、
    トークンの期限切れや通信エラーのUIフィードバックを一元管理できます。
client.interceptors.response.use(
  res => res,
  err => {
    // 共通エラーハンドリング
    return Promise.reject(err);
  }
);

✅ まとめ

OpenAPI + TypeScript + Axios によって、VueアプリのAPI通信は次のように進化します：

  • 🚫 型のズレをなくす
  • 🚀 実装スピードUP（コード自動生成）
  • 🛡️ 型安全で保守性の高い構成

今後は、エラーレスポンス（バリデーションエラーなど）も共通型で扱うことで、さらに堅牢な設計ができます。

Discussion