tskaigi-hokuriku2025-typespec-poc

TypeSpecを使用したOpenAPI仕様管理とフロントエンド開発のモノレポプロジェクトです。

📋 概要

このプロジェクトは、TypeSpecを使用してAPI仕様を定義し、
OpenAPI仕様書と型定義を自動生成することで、
フロントエンドとバックエンド間の型安全性を確保します。

主な特徴

• TypeSpecによるAPI定義: 型安全なAPI仕様の記述
• 自動型生成: OpenAPI仕様からTypeScript型定義を自動生成
• モノレポ構成: pnpm workspacesによる効率的なパッケージ管理
• 新旧API対応: レガシーAPIと新APIの並行管理

🏗️ プロジェクト構成

tskaigi-hokuriku2025-typespec-poc/
├── packages/
│   ├── typespec/          # TypeSpec定義とOpenAPI生成
│   │   ├── spec/
│   │   │   ├── legacy/   # レガシーAPI定義
│   │   │   └── new/      # 新API定義
│   │   ├── types/        # 生成された型定義
│   │   └── docs/         # 生成されたAPIドキュメント
│   └── frontend/         # Nuxtフロントエンド
│       └── app/
│           └── apis/     # API型定義の利用
├── package.json
└── pnpm-workspace.yaml

🚀 セットアップ

必要要件

• Node.js 18以上
• pnpm 10.22.0以上

インストール

# 依存関係のインストール
pnpm install

📦 パッケージ

@typespec-poc/typespec

TypeSpec定義からOpenAPI仕様書と型定義を生成するパッケージです。

主なコマンド

# すべてのAPI仕様をビルド
pnpm typespec build

# レガシーAPIのみビルド
pnpm typespec build:legacy

# 新APIのみビルド
pnpm typespec build:new

# 仕様のリント
pnpm typespec spec:lint:legacy
pnpm typespec spec:lint:new

出力内容

• OpenAPI仕様書 (YAML): combined-openapi-<legacy|new>.yaml
• APIドキュメント (HTML): docs/redoc-static-<legacy|new>.html
• TypeScript型定義: types/schemas/<legacy|new>/**/*.ts

@typespec-poc/frontend

Nuxtベースのフロントエンドアプリケーションです。

主なコマンド

# 開発サーバー起動
pnpm frontend run:dev

# 型チェック
pnpm frontend typecheck

# ビルド
pnpm frontend build

🔄 ワークフロー

1. API仕様の定義

packages/typespec/spec/<legacy|new>/ 配下にTypeSpecファイルを作成します。

// packages/typespec/spec/new/models/search/user.tsp
import "@typespec/http";

using TypeSpec.Http;

namespace Search;

model User {
  id: string;
  name: string;
  email: string;
}

2. 型定義の生成

pnpm typespec build

これにより以下が生成されます：

• OpenAPI仕様書
• TypeScript型定義
• APIドキュメント

3. フロントエンドでの利用

生成された型定義は自動的にフロントエンドパッケージに同期されます。

// packages/frontend/app/apis/search/types/index.ts
import type { paths } from '~/apis/types/schemas/new/Search'

type SearchUserPath = paths['/api/search/users']['get']
export type SearchUserResponse = SearchUserPath['responses'][200]['content']['application/json']

📝 開発ガイド

新しいAPI定義の追加

1. packages/typespec/spec/<legacy|new>/models/ または features/ にTypeSpecファイルを作成
2. 対応する main.tsp にインポートを追加
3. pnpm typespec build を実行
4. 生成された型定義をフロントエンドで利用

レガシーAPIから新APIへの移行

1. インポートパスの legacy を new に変更
2. エンドポイントパスを新しいものに更新
3. Request/Response型の差分を調整
4. 型エラーを修正

詳細は packages/typespec/README.md を参照してください。

🛠️ 技術スタック

• TypeSpec: API仕様定義
• OpenAPI 3.0: API仕様書フォーマット
• TypeScript: 型定義言語
• Nuxt 4: フロントエンドフレームワーク
• pnpm: パッケージマネージャー
• Redocly: APIドキュメント生成

📄 ライセンス

MIT

🤝 コントリビューション

プロジェクトへの貢献を歓迎します。Issue や Pull Request をお気軽にお送りください。