OpenAPI仕様書をClaude Codeで管理する

APIファースト開発では、実装前にOpenAPI仕様書をしっかり整備することが重要です。しかし、YAMLの構文エラーやスキーマの整合性チェックは地味に手間がかかりますよね。Claude Codeを活用すれば、仕様書の作成からバリデーション、コード生成まで一気通貫で進められます。

OpenAPI仕様書をゼロから作成する

まずはClaude Codeに仕様書の雛形を作ってもらいましょう。プロンプトで要件を伝えるだけで、正確なYAMLを生成できます。

ユーザー管理APIのOpenAPI 3.0仕様書を作成してください。
エンドポイントは以下の通りです。
- GET /users: ユーザー一覧取得（ページネーション対応）
- POST /users: ユーザー作成
- GET /users/{id}: ユーザー詳細取得
- PUT /users/{id}: ユーザー更新
- DELETE /users/{id}: ユーザー削除

レスポンスのエラーハンドリングも含めてください。

このように具体的なエンドポイントと要件を伝えると、components/schemas を活用した再利用性の高い仕様書を出力してくれます。既存の仕様書がある場合は、ファイルをそのまま貼り付けて「このエンドポイントを追加してください」と伝えるだけでOKです。

※エンドポイント: APIにアクセスするためのURL。例: `/api/users` や `/api/posts/123` など。※プロンプト: AIへの指示文。Claude Codeへの指示の質がそのまま出力の質に影響する。※API: Application Programming Interface の略。外部サービスとプログラム間でデータをやりとりするための接続口。

バリデーションと品質チェックを自動化する

生成した仕様書は必ずバリデーションを通しましょう。swagger-cli を使って構文チェックを行います。

# swagger-cliのインストール
npm install -g @apidevtools/swagger-cli

# バリデーション実行
swagger-cli validate openapi.yaml

エラーが出たら、そのエラーメッセージをそのままClaude Codeに貼り付けてください。「このエラーを修正してください」と伝えるだけで、該当箇所を特定して修正案を提示してくれます。$ref の循環参照や必須フィールドの漏れなど、複雑なエラーも的確に解消できます。

※npm: Node.jsのパッケージ管理ツール。`npm install` でライブラリをインストールする。

スタブサーバーとクライアントコードを生成する

仕様書が固まったら、openapi-generator-cli でコードを自動生成できます。

# TypeScript用のAPIクライアントを生成
npx @openapitools/openapi-generator-cli generate \
  -i openapi.yaml \
  -g typescript-axios \
  -o ./src/generated/api

生成されたコードに修正が必要なときも、Claude Codeが頼りになります。「生成されたコードにエラーハンドリングのラッパーを追加してください」のように指示すれば、プロジェクトの既存コードスタイルに合わせた実装を提案してくれます。仕様書の変更が生じた場合も、差分を伝えることで影響範囲の確認や再生成の手順をスムーズに進められます。

※TypeScript: JavaScriptに型定義を追加した言語。型チェックによりバグを事前に発見しやすくなる。