OpenAPI クライアント
フロントエンドからバックエンドへの型安全なアクセスを実現する仕組み。
バックエンドの #[utoipa::path] アノテーションから OpenAPI スキーマを自動生成し、
フロントエンドは生成された TypeScript 型を通じて API を呼び出す。
全体の流れ
[Rust utoipa アノテーション]
↓ cargo run --bin generate_schema
[openapi.json (一時ファイル)]
↓ openapi-typescript
[src/api/schema.d.ts (gitignore済み)]
↓ import
[src/api/client.ts (openapi-fetch)]
↓
[各コンポーネント・ローダーで型安全に使用]型の再生成
バックエンドの API を変更したら以下を実行する。サーバーの起動は不要。
cd apps/web
pnpm generate:api内部では以下の処理が順に走る。
cargo run --bin generate_schema— Rust バイナリが OpenAPI JSON を stdout に出力openapi-typescript— JSON からsrc/api/schema.d.tsを生成- 一時ファイルを削除
schema.d.ts は .gitignore に登録されており、コミットされない。
開発者それぞれが手元で生成する運用とする。
APIクライアントの使い方
src/api/client.ts の apiClient を import して使う。
import { apiClient } from '@/api/client'
// GET
const { data, error } = await apiClient.GET('/v1/auth/me')
// POST (リクエストボディも型補完される)
const { data, error } = await apiClient.POST('/v1/auth/login', {
body: { email: 'user@example.com', password: 'password123' }
})
// パスパラメータあり
const { data, error } = await apiClient.GET('/v1/folders/{id}', {
params: { path: { id: 'xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx' } }
})存在しないパスやリクエストボディの型ミスはコンパイル時にエラーになる。
環境別の baseUrl
開発環境のプロキシ
vite.config.ts で /v1 以下のリクエストをバックエンドに転送している。
転送先のデフォルトは http://localhost:8080。変更する場合は .env.local に設定する。
API_BASE_URL=http://localhost:8080本番環境
フロントエンドとバックエンドが別ドメイン・別ポートで動作する場合は
.env に VITE_API_BASE_URL を設定する。
VITE_API_BASE_URL=https://api.example.com