# feat: OpenAPI 型生成への完全移行 — 主要レスポンス（ADR-0007 Phase 2）

[yusuke0610]

概要

ADR-0007 の段階移行プランに従い、Phase 2（主要レスポンスの完全移行） を実施する。api/githubLink.ts と api/auth.ts の手書き DTO interface を全削除し、OpenAPI から生成した backend クラス名の型（generated.ts → 薄い再エクスポート層 api/types.ts）へ完全移行する。

• ADR: docs/adr/0007-openapi-typescript-codegen.md（status: Accepted）
• 前提 PR: Phase 0（基盤）+ Phase 1（api/shared.ts パイロット）

背景

Phase 1 で TaskStatusResponse のパイロット移行と CI ドリフト検知の機能確認が完了した。Phase 2 では ADR の命名統一マップに沿って、GitHub 連携・認証まわりの主要レスポンス型を BE 名へ統一し、手書き interface を撤去する。

変更内容

backend — 完全移行の前提整備

• backend/app/schemas/github_link.py: CachedGitHubLinkResponse.result を Optional[Dict[str, Any]] → Optional[GitHubLinkResponse] に型を絞った。
  • これにより GitHubLinkResponse / ContributionCalendar / ContributionDay が OpenAPI スキーマに出力され、frontend で生成型に移行しても型安全が後退しない（緩い result のまま移行すると Record<string, never> 相当の untyped になり退化する）。
  • cache.result は github_link_service.py で GitHubLinkResponse(...).model_dump() を保存したものなので、型を絞っても round-trip は安全（backend テストで実証）。
  • 未使用になった Any import を除去。

frontend — 手書き DTO の完全移行

• api/types.ts（再エクスポート層）: Phase 2 対象の 10 型を BE 名のまま追加。
  ProgressResponse / SubProgress / TaskAcceptedResponse / GitHubLinkResponse / ContributionDay / ContributionCalendar / CachedGitHubLinkResponse / GitHubLoginUrlResponse / TokenResponse（+ Phase 1 の TaskStatusResponse）。
• api/githubLink.ts: 手書き interface（TaskProgress / GitHubLinkResponse / ContributionDay / ContributionCalendar / CachedGitHubLinkResponse）を全削除し再エクスポート層を参照。
  • getGitHubLinkProgress(): Promise<ProgressResponse>（旧 TaskProgress）
  • runGitHubLink / retryGitHubLink: 戻り値を { status: string } → TaskAcceptedResponse
  • getGitHubLinkCache(): Promise<CachedGitHubLinkResponse>
• api/auth.ts: 手書き AuthResponse を削除し TokenResponse へ統一。login-url の inline 型 { authorization_url, state } を GitHubLoginUrlResponse に置換。

frontend — 消費側の追従

• hooks/useAsyncTaskPage.ts: TaskProgress → ProgressResponse。loadCache の status を string | null 許容に（論点B）。
• components/github-link/ContributionHeatmap.tsx: 生成型で ContributionCalendar.weeks が optional 化したため、const weeks = useMemo(() => calendar.weeks ?? [], [calendar.weeks]) で安定参照を導出し全箇所を差し替え。
• components/github-link/GitHubLinkDashboard.tsx: loadCache の result を cache.result ?? null に正規化（CachedGitHubLinkResponse.result が optional のため）。

移行しないもの（ADR 準拠）

• GitHubLinkPayload（request 型・include_forks?）: response DTO ではなく、retryGitHubLink({}) の省略呼び出しを保つため手書きで温存（ADR 論点A: 入出力兼用 schema の Input 側は default 値の解釈差があるため別管理）。
• api/client.ts の 401/CSRF/Cookie 認証ロジック、api/paths.ts の PATHS（codegen 対象外）。

既知の論点への対応（ADR）

• 論点B（optional/required の解釈ズレ）: backend の str | None / default_factory フィールドが生成型で string | null / optional になる。消費側（useAsyncTaskPage の status、ContributionHeatmap の weeks、GitHubLinkDashboard の result）を null/undefined 合体で追従。実行時挙動は不変。

検証

• ✅ make ci green（lint + vitest 189 passed + build）。
• ✅ backend 68 tests passed（result 型絞り込みのシリアライズ安全性を実 DB で実証）。
• ✅ E2E 22 passed（Phase 2 必須。GitHub 連携 / 通知 / 認証の UI フロー）。
• ✅ codegen 冪等: make codegen-types 再実行で generated.ts に差分なし（CI codegen-drift ジョブは clean）。
• ✅ 削除した FE 独自名（TaskProgress / AuthResponse）の残参照ゼロを確認。

今後（別 PR）

• Phase 3: types.ts の CareerResume*（→Resume*）/ BlogAccount（→BlogAccountResponse）/ MasterItem 系を完全移行。payloadBuilders.ts / formMappers.ts の追従。E2E 必須。

Summary by CodeRabbit

• Improvements

  • Consolidated type definitions for GitHub profile analysis across frontend and backend for improved type safety.
  • Enhanced handling of optional contribution calendar data fields to prevent errors when data is unavailable.

• Documentation

  • Updated architectural decision documentation for OpenAPI schema and TypeScript integration alignment.

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro Plus

Run ID: ed13533d-3d0f-45a9-9e90-e66238bd2f37

📥 Commits

Reviewing files that changed from the base of the PR and between e05ee40 and 66ca031.

📒 Files selected for processing (9)

• backend/app/schemas/github_link.py
• docs/adr/0007-openapi-typescript-codegen.md
• frontend/src/api/auth.ts
• frontend/src/api/generated.ts
• frontend/src/api/githubLink.ts
• frontend/src/api/types.ts
• frontend/src/components/github-link/ContributionHeatmap.tsx
• frontend/src/components/github-link/GitHubLinkDashboard.tsx
• frontend/src/hooks/useAsyncTaskPage.ts

---

📝 Walkthrough

Walkthrough

This PR completes ADR-0007 Phase 2 by aligning OpenAPI schema types across the backend and frontend. The backend schema now types CachedGitHubLinkResponse.result as GitHubLinkResponse, frontend generated types include the full GitHub analysis response structure, and API clients consolidate to shared type definitions. Consuming components safely handle optional fields.

Changes

ADR-0007 Phase 2: Schema Typing and Consolidation

Layer / File(s)	Summary
Backend schema and migration documentation backend/app/schemas/github_link.py, docs/adr/0007-openapi-typescript-codegen.md	Backend CachedGitHubLinkResponse.result is typed from untyped Dict[str, Any] to GitHubLinkResponse. ADR-0007 Phase 2 documentation is updated to reflect schema alignment, type migrations, optional handling, and consumer updates.
OpenAPI codegen schema definitions frontend/src/api/generated.ts	Adds typed schema definitions for GitHubLinkResponse (with optional contribution_calendar, language breakdown, and summary fields), ContributionCalendar, and ContributionDay. Retypes CachedGitHubLinkResponse.result from Record<string, never> to GitHubLinkResponse | null.
Type alias and re-exports frontend/src/api/types.ts	Introduces Schemas type alias for components["schemas"] and re-exports all OpenAPI schemas: TaskAcceptedResponse, ProgressResponse, SubProgress, ContributionDay, ContributionCalendar, GitHubLinkResponse, CachedGitHubLinkResponse, GitHubLoginUrlResponse, TokenResponse.
API client type consolidation frontend/src/api/auth.ts, frontend/src/api/githubLink.ts	auth.ts imports and uses TokenResponse and GitHubLoginUrlResponse; functions return typed responses. githubLink.ts imports task/response types from ./types and updates function signatures to return TaskAcceptedResponse and ProgressResponse; local type definitions are removed.
Hook and component updates frontend/src/hooks/useAsyncTaskPage.ts, frontend/src/components/github-link/ContributionHeatmap.tsx, frontend/src/components/github-link/GitHubLinkDashboard.tsx	useAsyncTaskPage uses ProgressResponse instead of TaskProgress and widens loadCache.status to allow null. ContributionHeatmap normalizes optional calendar.weeks via useMemo for all calculations. GitHubLinkDashboard normalizes cached result from undefined to null.

Estimated code review effort

🎯 3 (Moderate) | ⏱️ ~25 minutes

Possibly related PRs

• yusuke0610/devforge#281: Introduces and persists the GitHub contribution_calendar data in the same schemas and components that this PR types and consolidates.
• yusuke0610/devforge#289: Establishes the OpenAPI→frontend/src/api/generated.ts codegen pipeline and initial response models (TaskAcceptedResponse, GitHubLoginUrlResponse); this PR consumes and aligns those generated types across the frontend.

Poem

🐰 Schemas and types, now all aligned,
From backend to frontend, so refined!
No more loose dicts or any in sight,
GitHubLinkResponse shines so bright!
One source of truth, the rabbit declares,
Phase 2 complete—hopping with care! 🎉

🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 66.67% which is insufficient. The required threshold is 80.00%.	Write docstrings for the functions missing them to satisfy the coverage threshold.

✅ Passed checks (4 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title accurately describes the main change: completing ADR-0007 Phase 2 migration to OpenAPI-generated types for major response types.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

✨ Finishing Touches

📝 Generate docstrings

• Create stacked PR
• Commit on current branch

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch feat/openAPI-typescript

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands and usage tips.}