本記事ではCursorとAIの力を活用して、OpenAPI仕様からTypeScript SDKを自動生成する方法を紹介します。APIクライアントの実装は時間と労力を要する作業ですが、AIを活用することで効率化できます。
なぜSDKを自動生成するのか？
APIを利用する際、SDKがあれば様々なメリットがあります。TypeScriptの型システムによるコード補完や型チェックが利用できる点、複雑なAPIリクエストをシンプルなメソッド呼び出しに抽象化できる点などが挙げられます。またコードにドキュメントが組み込まれるため使い方も明確になり、APIに変更があった場合もSDKを更新するだけで対応可能です。
SDKを手動で作成するのは煩雑な作業ですが、Cursorを利用することで短時間での作成が可能となります。
準備するもの
Cursor（AI搭載コードエディタ）が必要となります。インストールがまだの場合はこちらからダウンロードすることができます。また、対象APIのOpenAPI仕様書（YAMLまたはJSON形式）とSDKをテストするためのNode.js環境も用意する必要があります。
手順
STEP 1: プロジェクトの準備
まず、SDKを格納するためのプロジェクトディレクトリを作成します。
mkdir my-api-sdk
cd my-api-sdk
npm init -y
npm install typescript @types/node --save-dev
npx tsc --init
STEP 2: 必要なライブラリのインストール
APIクライアントに必要なライブラリをインストールします。
npm install isomorphic-fetch
npm install --save-dev @types/isomorphic-fetch
STEP 3: OpenAPI仕様をCursorに読み込む
OpenAPI仕様ファイルをプロジェクトに配置するか、URLでアクセスできる場合はその参照先をCursorに指示します。
このOpenAPI仕様からTypeScript SDKを作成してください：[OpenAPI仕様のURL、または仕様の内容をペースト]
STEP 4: SDKの設計を指示する
Cursorに対して、どのようなSDKを作成したいか具体的に指示します。
以下の条件でSDKを生成してください：
- src/sdkディレクトリに作成
- APIの各エンドポイントに対応するサービスクラスを作成
- GET、POST、PATCH、DELETEなどのHTTPメソッドすべてに対応
- レスポンスとリクエストの型定義を含める
- エラーハンドリングの仕組みを組み込む
- ドキュメント付きのコード
- 使用例を含める
このような指示を出すことで、Cursorは指示に基づいてSDKのコードを生成します。
STEP 5: 生成されたコードの確認と修正
生成されたコードについて確認を進めましょう。必要に応じて手動で調整する場合もあります。チェックポイントとしては、型定義の不足や誤り、メソッド名の適切さ、エラーハンドリングの十分さなどでしょうか。効率的に進めるには、Cursorに「SDKの〇〇部分を修正してください」と指示することもできます。
STEP 6: SDKのテスト
生成されたSDKを実際に使用して、期待通りに動作するか確認します。テストコードも作成しておくことが望ましいでしょう。
// 例：SDKを使ったテスト
import { createApiSdk } from './src/sdk';
const sdk = createApiSdk({
apiKey: 'YOUR_API_KEY',
baseUrl: 'https://api.example.com/v1'
});
async function testSdk() {
try {
const users = await sdk.users.getUsers();
console.log('ユーザー一覧:', users);
} catch (error) {
console.error('エラー:', error);
}
}
testSdk();
実際にやってみた例 - とあるSaaSのAPI SDK
今回は、とあるSaaSのRESTful APIのSDKを生成しました。以下は生成したSDKの構造です。
src/sdk/
├── client.ts # 基本的なHTTPクライアント
├── index.ts # メインエントリーポイント
├── types.ts # 型定義
├── README.md # 使用方法ドキュメント
├── examples.ts # 使用例
└── services/ # APIサービスクラス
├── users.ts # ユーザー関連API
├── organizations.ts # 組織関連API
└── projects.ts # プロジェクト関連API
生成されたSDKの使用例
生成されたSDKは、このような実装・利用方法になっていました。よく見かける SaaS の SDK っぽい感じになっているかなーと思います。
import { createSaasApiSdk } from 'saas-api-sdk';
// SDKの初期化
const sdk = createSaasApiSdk({
apiKey: 'YOUR_API_KEY',
apiToken: 'YOUR_API_TOKEN'
});
// ユーザー一覧の取得
const users = await sdk.users.getUsers({
page: 1,
per_page: 20,
include_details: true
});
// 新規組織の作成
const newOrg = await sdk.organizations.createOrganization({
name: '株式会社サンプル',
industry: 'technology',
size: 'medium'
});
// プロジェクト情報の更新
const updatedProject = await sdk.projects.updateProject(123, {
name: 'プロジェクト名（更新）',
status: 'completed'
});
SDKを自動生成する際のポイント
自動生成をさせる場合、 Cursor に何を期待しているのかを明確に伝えることが重要です。一度にすべてを生成するのではなく、基本構造→型定義→サービスクラスといった順で指示すると良い結果が得られる可能性が高まります。
また、生成されたコードはそのままにせず、レビューして足りない部分や改善点を指摘して修正することをお勧めします。「このヘルパーメソッドも追加してほしい」といった提案も効果的です。
まとめ
Cursorを使ったOpenAPI仕様からのSDK自動生成は、APIクライアント実装の労力を大幅に削減します。手動で書くと何日もかかる作業が、AIの助けを借りれば数十分で終わらせることができます。
特にTypeScriptの型安全性を活かしたいプロジェクトでは、この方法が役立ちます。生成されたSDKは出発点として扱い、必要に応じてカスタマイズしていくとよいでしょう。
Discussion