foundation-api-integration

name: foundation-api-integration description: 初期的なBackend API テスト実行・OpenAPI スキーマ出力・Frontend orval 再生成・型チェック allowed-tools: - Read - Write - Edit - Bash

Slice 0-6: API Integration & OpenAPI Schema

Backend API のテスト実行、OpenAPI スキーマ出力、Frontend orval 再生成、型チェックを一貫して行うスキル。

Purpose

Backend と Frontend の統合を準備する：

1. Backend テスト実行確認
2. OpenAPI スキーマを JSON 出力
3. Frontend orval で API client を再生成
4. Frontend 型チェック実行
5. 統合準備完了確認

When to use

• Slice 0-1 ～ 0-5（Foundation Phase）を全て完了した後に実行
• Backend と Frontend の統合を開始する前に実行
• API 仕様を確定して、Client SDK を自動生成したい

Prerequisites

• Slice 0-1: Backend プロジェクト初期化完了
• Slice 0-2: PostgreSQL Docker セットアップ完了
• Slice 0-3: Database 設計・実装完了
• Slice 0-4: 認証ミドルウェア実装完了
• Slice 0-5: Frontend プロジェクト初期化完了
• Backend app/main.py に最低1つのエンドポイント実装済み

Outputs

OpenAPI スキーマファイル：

backend/
└── openapi.json          # FastAPI から出力された OpenAPI スキーマ

frontend/
├── src/services/         # orval が生成した API client（自動更新）
│   └── api/
│       └── generated.ts  # Auto-generated by orval
└── .orval/
    └── openapi.json      # ローカルキャッシュ

Procedure

Step 1: 前提確認

Backend が最低限のエンドポイントを持っていることを確認：

cd backend

# ヘルスチェックエンドポイントがあるか確認
grep -r "GET\|POST\|PUT\|DELETE" app/api/v1/endpoints/ || echo "エンドポイントなし"

確認項目:

• app/main.py に /api/v1/health が実装されている
• または他の API エンドポイント（/api/v1/auth/login など）が実装されている

Step 2: Backend ユニットテスト実行

Backend のテストが成功することを確認：

cd backend

# テスト実行
uv run pytest tests/ -v

# または特定ファイル
uv run pytest tests/test_health.py -v

確認項目:

• テストが全て成功する
• テストカバレッジが適切（60% 以上推奨）
• エラーメッセージがない

Step 3: 型チェック・Lint 実行

Backend コードの品質を確認：

cd backend

# Format 確認（修正なし）
uv run ruff format --check app tests

# Lint チェック
uv run ruff check app tests

確認項目:

• Lint エラーがない
• Format がアラインされている

Step 4: OpenAPI スキーマを出力

FastAPI から OpenAPI スキーマをエクスポート：

cd backend

# スキーマを出力
uv run python scripts/export_openapi.py -o openapi.json

# 出力確認
ls -la openapi.json
head -50 openapi.json

確認項目:

• backend/openapi.json が作成された
• ファイルサイズが 1KB 以上
• JSON 形式が有効
• "paths" に API エンドポイントが列挙されている

例:

{
  "openapi": "3.0.0",
  "info": {
    "title": "Training Sprint 2 API",
    "version": "0.1.0"
  },
  "paths": {
    "/api/v1/health": {
      "get": {
        "operationId": "health_check",
        "summary": "ヘルスチェック"
      }
    }
  }
}

Step 5: Frontend orval 設定確認

Frontend の orval 設定が正しいことを確認：

cd frontend

# orval 設定を確認
cat orval.config.ts

# 設定内容:
# - input.target が ../../backend/openapi.json を指す
# - output.target が src/services/api/generated.ts を指す

期待される設定（orval.config.ts の一部）:

export default defineConfig({
  api: {
    input: {
      target: '../../backend/openapi.json',
    },
    output: {
      target: './src/services/api/generated.ts',
      client: 'axios',
    },
  },
})

Step 6: Frontend orval で API client を再生成

Backend の OpenAPI スキーマから、Frontend の API client を再生成：

cd frontend

# orval を実行
npm run orval

# または watch モード
npm run orval:watch

確認項目:

• src/services/api/generated.ts が更新された（ファイル日時を確認）
• エラーメッセージなし
• 生成されたファイルが TypeScript として有効

例出力:

$ npm run orval
> orval

Generating schema from ... (backend/openapi.json)
✓ Generated API client: src/services/api/generated.ts

Step 7: 生成されたコードを確認

生成された API client が期待通りに含まれているかを確認：

cd frontend

# 生成ファイルを確認
head -100 src/services/api/generated.ts

# または grep で関数を確認
grep "export.*function\|export.*const" src/services/api/generated.ts | head -20

期待される内容:

// Auto-generated by orval - Do not edit
import { AxiosInstance } from 'axios'

// APIクライアント関数が自動生成されている
export const getApiV1Health = (options?: AxiosRequestConfig) => {
  return instance.get(`/api/v1/health`, options)
}

export const postApiV1AuthLogin = (
  data: LoginRequest,
  options?: AxiosRequestConfig
) => {
  return instance.post(`/api/v1/auth/login`, data, options)
}

Step 8: Frontend 型チェック

Frontend の TypeScript コンパイル・型チェックを実行：

cd frontend

# 型チェック実行
npm run typecheck

# または tsc で直接実行
npx tsc --noEmit

確認項目:

• 型チェックエラーなし
• インポートが全て解決されている
• API client の型が認識されている

Step 9: Frontend テスト実行

Frontend のテストが実行できることを確認：

cd frontend

# テスト実行（1 回のみ）
npm run test

# または watch モード
npm run test -- --watch

確認項目:

• テストが実行される（失敗していてもOK、実行環境確認が目的）
• ブラウザや Node.js のセットアップエラーがない

Step 10: 統合準備完了確認

全ての準備が完了したことを確認：

# Backend
cd backend
echo "=== Backend Status ==="
echo "OpenAPI schema: $([ -f openapi.json ] && echo 'OK' || echo 'MISSING')"
echo "Tests: $(uv run pytest tests/ -q 2>&1 | tail -1)"

# Frontend
cd ../frontend
echo ""
echo "=== Frontend Status ==="
echo "API client: $([ -f src/services/api/generated.ts ] && echo 'OK' || echo 'MISSING')"
echo "Type check: $(npm run typecheck > /dev/null 2>&1 && echo 'OK' || echo 'FAILED')"

期待される出力:

=== Backend Status ===
OpenAPI schema: OK
Tests: 10 passed

=== Frontend Status ===
API client: OK
Type check: OK

チェックリスト

Slice 0-6 完了時

• Backend テスト全て成功
• Backend Lint・Format 確認完了
• OpenAPI スキーマ（openapi.json）を出力完了
• Frontend orval で API client を再生成完了
• Frontend 型チェック成功
• Frontend テスト実行環境確認完了
• 統合準備完了確認完了

次のステップ

Slice 0-1 ～ 0-6（Foundation Phase）完了後は、Phase 1: Feature Development を開始

Foundation Phase（Slice 0-1～0-6）完了
  ↓
Phase 1: Feature Development
├─ Vertical Slice Architecture で機能実装
├─ Backend ～ Frontend を一貫してTDD実装
└─ fullstack-integration-coordinator で指揮

注意事項

• orval生成コードは編集しない: generated.ts は自動生成ファイル。変更は orval.config.ts または Backend で行う
• OpenAPI スキーマは Backend 由来: Frontend が Backend に依存。Backend API が確定してから Frontend 開発を進める
• 型チェックは必須: Frontend 開発の前提条件として、型チェックエラーが0であることを確認

トラブルシューティング

orval 実行時 "Cannot find module" エラー

# orval.config.ts のパスを確認
cat orval.config.ts
# 相対パスが正しいか確認: '../../backend/openapi.json'

# openapi.json の存在を確認
ls -la ../../backend/openapi.json

型チェックエラー "Cannot find type definition"

# Frontend 依存をインストール
npm install

# orval を再実行
npm run orval

# TypeScript cache をクリア
rm -rf node_modules/.vite/deps/

# 型チェック再実行
npm run typecheck

OpenAPI スキーマが空

# Backend main.py に最低1つのエンドポイント実装確認
grep -r "@app\|@router" backend/app/

# エンドポイントがない場合は、Slice 0-1 を再確認

参考資料

• FastAPI OpenAPI Documentation
• orval Documentation
• TanStack Query Documentation