Claude CodeでSwagger/OpenAPIドキュメントを自動生成する方法【完全ガイド】

API開発において、ドキュメント整備は最も後回しにされがちなタスクの一つです。手動でSwagger仕様書を書くのは面倒で、実装とドキュメントが乖離するのは日常茶飯事。その結果、フロントエンド・バックエンド間の認識齟齬やバグが頻発します。

Claude Codeを使えば、既存コードからのOpenAPIドキュメント自動生成から、スキーマファースト設計、CI/CDとの連携まで、API ドキュメント運用を根本的に改善できます。

Swagger/OpenAPIとは？ — APIドキュメントの標準仕様

OpenAPI Specificationの基本構造

**OpenAPI Specification（OAS）**は、RESTful APIの構造を記述するための業界標準フォーマットです。旧称Swagger Specificationとも呼ばれ、現在のバージョンは3.1がメインです。

OpenAPI仕様書の基本的な構成要素は以下の通りです。

• info: APIのタイトル、バージョン、説明
• servers: APIのベースURL
• paths: エンドポイントの定義（HTTPメソッド、パラメータ、レスポンス）
• components/schemas: データモデルの定義
• security: 認証方式の定義

openapi: 3.1.0
info:
  title: SES案件管理API
  version: 1.0.0
  description: SES案件の検索・管理を行うAPI
servers:
  - url: https://api.ses-base.com/v1
paths:
  /projects:
    get:
      summary: 案件一覧を取得
      parameters:
        - name: skill
          in: query
          schema:
            type: string
      responses:
        '200':
          description: 成功
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ProjectList'

なぜAPIドキュメント管理が難しいのか

多くのプロジェクトでAPIドキュメントが放置される理由は明確です。

1. 手動メンテナンスのコスト: エンドポイントが増えるたびにYAML/JSONを手書きするのは非効率
2. 実装との乖離: コード変更時にドキュメント更新を忘れる
3. チーム間の同期コスト: フロント・バックエンドで仕様認識がずれる
4. バージョン管理の複雑さ: API v1とv2の仕様を並行管理する必要がある

ここでClaude Codeの出番です。

Claude Codeで既存APIからOpenAPIドキュメントを逆生成する

コードベース解析によるエンドポイント抽出

まず、既存のAPIコードベースからSwagger仕様書を自動生成する方法を紹介します。

claude "このプロジェクトの全APIエンドポイントを分析し、
OpenAPI 3.1形式の仕様書を生成してください。
以下を含めてください：
1. 全エンドポイントのパス・HTTPメソッド・パラメータ
2. リクエストボディのスキーマ（TypeScript型定義から推論）
3. レスポンスのスキーマ（各ステータスコード別）
4. 認証方式（Bearer token/API key）
5. パスパラメータとクエリパラメータの説明
出力: docs/openapi.yaml"

Claude Codeは200Kトークンのコンテキストウィンドウを活用し、プロジェクト全体のコードを一度に解析します。Express、FastAPI、NestJS、Spring Bootなど、主要なフレームワークのルーティング定義を自動で認識し、正確なOpenAPI仕様書を生成します。

TypeScript型定義からスキーマを自動推論

TypeScriptプロジェクトでは、既存の型定義からOpenAPIスキーマを生成できます。

claude "src/types/ ディレクトリの全TypeScript型定義を解析し、
対応するOpenAPI componentsスキーマを生成してください。
- interfaceとtypeの両方を変換
- enumはOpenAPI enumに対応させる
- optional fieldはrequiredから除外
- ネストされた型はrefで参照
- JsDocコメントはdescriptionに変換"

例えば以下のTypeScript型定義があるとします。

/** SES案件情報 */
interface Project {
  /** 案件ID */
  id: string;
  /** 案件名 */
  title: string;
  /** 必須スキル一覧 */
  requiredSkills: Skill[];
  /** 月単価（万円） */
  monthlyRate?: number;
  /** 勤務形態 */
  workStyle: 'remote' | 'onsite' | 'hybrid';
  /** 募集開始日 */
  startDate: string;
}

Claude Codeはこれを以下のOpenAPIスキーマに変換します。

components:
  schemas:
    Project:
      type: object
      description: SES案件情報
      required:
        - id
        - title
        - requiredSkills
        - workStyle
        - startDate
      properties:
        id:
          type: string
          description: 案件ID
        title:
          type: string
          description: 案件名
        requiredSkills:
          type: array
          items:
            $ref: '#/components/schemas/Skill'
          description: 必須スキル一覧
        monthlyRate:
          type: number
          description: 月単価（万円）
        workStyle:
          type: string
          enum: [remote, onsite, hybrid]
          description: 勤務形態
        startDate:
          type: string
          format: date
          description: 募集開始日

Express/NestJS/FastAPIのルーティング解析

フレームワーク固有のルーティング定義も自動で解析できます。

claude "src/routes/ のExpressルーター定義を解析し、
各エンドポイントのOpenAPI paths定義を生成してください。
- ミドルウェアから認証要否を判定
- バリデーション（Joi/Zod）からパラメータ制約を抽出
- エラーハンドラーからエラーレスポンスを特定
- ルートグループからタグを自動付与"

スキーマファースト開発ワークフローの構築

API設計 → コード生成の逆転発想

従来の「コードを書いてからドキュメントを追加」ではなく、先にOpenAPI仕様書を設計してからコードを生成するスキーマファーストアプローチが、チーム開発では有効です。

claude "docs/openapi.yaml の仕様書から以下を生成してください：
1. TypeScript型定義（src/types/api.ts）
2. Express/NestJSルーターの雛形（src/routes/）
3. Zodバリデーションスキーマ（src/validators/）
4. Prismaスキーマの更新提案（prisma/schema.prisma）
5. APIクライアント（src/client/api.ts）"

スキーマファースト開発の利点は以下の通りです。

• フロント・バックエンドの並行開発: 仕様書が確定した時点で両チームが着手可能
• モックサーバーの自動生成: 仕様書からモックデータを生成し、フロント開発を加速
• コードレビューの効率化: 仕様変更とコード変更が常に対応
• 型安全性の担保: 仕様書から生成した型でコンパイル時にエラーを検出

インタラクティブなスキーマ設計セッション

Claude Codeの対話モードを活用して、APIスキーマをインタラクティブに設計することも可能です。

claude "新しいエンドポイント POST /api/v1/matching を設計してください。
ビジネス要件：
- SESエンジニアのスキルセットと案件の要件をマッチング
- マッチ度のスコア（0-100）を算出
- フィルタリング条件（勤務地、単価範囲、スキル）に対応
- ページネーション対応
設計上の制約：
- レスポンスタイムは200ms以内
- バッチ処理にも対応（最大50件同時）"

Claude Codeは要件を理解し、最適なリクエスト/レスポンス設計を提案してくれます。

paths:
  /api/v1/matching:
    post:
      summary: エンジニア-案件マッチング
      tags: [Matching]
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [engineerIds]
              properties:
                engineerIds:
                  type: array
                  items:
                    type: string
                  maxItems: 50
                filters:
                  type: object
                  properties:
                    location:
                      type: string
                      enum: [tokyo, osaka, remote]
                    minRate:
                      type: integer
                      minimum: 0
                    maxRate:
                      type: integer
                    skills:
                      type: array
                      items:
                        type: string
                pagination:
                  type: object
                  properties:
                    page:
                      type: integer
                      default: 1
                    limit:
                      type: integer
                      default: 20
                      maximum: 100
      responses:
        '200':
          description: マッチング結果
          content:
            application/json:
              schema:
                type: object
                properties:
                  matches:
                    type: array
                    items:
                      $ref: '#/components/schemas/MatchResult'
                  total:
                    type: integer
                  page:
                    type: integer

OpenAPIドキュメントの品質チェックと自動修正

Lintルールによるドキュメント品質管理

Claude Codeを使って、OpenAPI仕様書の品質チェックを自動化できます。

claude "docs/openapi.yaml を以下の観点で検証し、修正してください：
1. 全エンドポイントにdescriptionが設定されているか
2. レスポンスの全ステータスコード（200/400/401/404/500）が定義されているか
3. パラメータにexampleが付与されているか
4. スキーマのプロパティにdescriptionがあるか
5. 命名規則がcamelCaseで統一されているか
6. セキュリティ定義が全エンドポイントに適用されているか"

Spectral/Redocly CLIとの連携

Claude Codeは既存のOpenAPIリンティングツールとの連携も得意です。

claude "SpectralのカスタムルールセットとRedocly CLIの設定を作成してください。
ルール要件：
- エンドポイントのパスはケバブケース
- レスポンスにはrequestIdフィールドを必須
- ページネーションレスポンスには必ずtotalとpageを含める
- 日付フィールドはISO 8601形式のformat: date-time
- 配列パラメータにはmaxItemsを設定
.spectral.yml と redocly.yaml を出力してください"

実践例 — SES案件管理APIのドキュメント自動生成

プロジェクト構成の確認

ここでは実際のSES案件管理APIを例に、Claude Codeを使ったドキュメント生成ワークフローを紹介します。

ses-project-api/
├── src/
│   ├── routes/
│   │   ├── projects.ts      # 案件エンドポイント
│   │   ├── engineers.ts     # エンジニアエンドポイント
│   │   └── matching.ts      # マッチングエンドポイント
│   ├── types/
│   │   ├── project.ts       # 案件型定義
│   │   └── engineer.ts      # エンジニア型定義
│   ├── validators/
│   │   └── schemas.ts       # Zodバリデーション
│   └── middleware/
│       └── auth.ts           # 認証ミドルウェア
├── docs/
│   └── openapi.yaml          # ← ここに自動生成
└── package.json

ステップ1: コードベースからの仕様書一括生成

claude "src/ ディレクトリ全体を解析し、以下を生成してください：
1. docs/openapi.yaml - 完全なOpenAPI 3.1仕様書
2. docs/schemas/ - 各スキーマの個別YAMLファイル
3. docs/examples/ - 各エンドポイントのリクエスト/レスポンス例
全エンドポイントに日本語の説明を付けてください。"

ステップ2: Swagger UIでのプレビュー

生成した仕様書をSwagger UIでプレビューする設定もClaude Codeで自動化できます。

claude "swagger-ui-express を使って /api-docs でOpenAPI仕様書を
Swagger UIで表示する設定を追加してください。
- docs/openapi.yaml を読み込み
- 開発環境でのみ有効（NODE_ENV=development）
- カスタムCSS（ダークモード対応）を適用"

ステップ3: 変更検知とドキュメント同期

APIの実装に変更があった場合、ドキュメントとの乖離を自動検知する仕組みも構築できます。

claude "以下のCIステップを作成してください：
1. APIのルーティング定義からエンドポイント一覧を抽出
2. openapi.yaml のpaths定義と比較
3. 不一致がある場合はPRにコメント
4. 新しいエンドポイントが追加された場合はドキュメント更新PRを自動作成"

CI/CDパイプラインへの組み込み

GitHub Actionsでのドキュメント検証

name: API Documentation Check
on:
  pull_request:
    paths:
      - 'src/routes/**'
      - 'src/types/**'
      - 'docs/openapi.yaml'

jobs:
  validate-docs:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - name: OpenAPI Lint
        run: npx @redocly/cli lint docs/openapi.yaml
      - name: Schema Validation
        run: npx swagger-cli validate docs/openapi.yaml
      - name: Breaking Change Detection
        run: npx oasdiff breaking docs/openapi.yaml --base origin/main

ドキュメント自動デプロイ

claude "GitHub ActionsでOpenAPI仕様書の変更時に
以下を自動実行するワークフローを作成してください：
1. Redoc HTMLを生成してGitHub Pagesにデプロイ
2. Postmanコレクションを自動エクスポート
3. TypeScriptクライアントを再生成してnpmに公開
4. 変更ログを自動生成"

Claude CodeのCI/CD統合ガイドで、パイプライン構築の詳細を確認できます。

APIドキュメント運用のベストプラクティス

バージョニング戦略

APIのバージョン管理には以下の方式があります。Claude Codeで各方式に対応したドキュメント構造を自動生成できます。

方式	URL例	メリット	デメリット
URLパス	/api/v1/	明示的で分かりやすい	URLが冗長
ヘッダー	Accept-Version: v1	URLがきれい	発見性が低い
クエリ	?version=1	柔軟	キャッシュに影響

ドキュメントのメンテナンスサイクル

Claude Codeを活用した推奨メンテナンスサイクルは以下の通りです。

1. 毎PR: CIでOpenAPI lint + 乖離チェック実行
2. 毎スプリント: Claude Codeで仕様書の網羅性を再チェック
3. 毎リリース: APIクライアントの再生成とテスト
4. 四半期: 非推奨エンドポイントの棚卸しとドキュメント整理

チーム連携のためのドキュメント活用

ドキュメントは「書いて終わり」ではなく、チーム全体で活用してこそ価値があります。

• フロントエンド: 生成したTypeScriptクライアントをSDKとして使用
• QA: OpenAPI仕様書からテストケースを自動生成
• プロダクト: Swagger UIで仕様を確認し、要件との整合性をレビュー
• 外部パートナー: Redoc HTMLを公開して外部連携をスムーズに

Claude CodeでのAPI開発ガイドでは、APIの設計・実装についてより詳しく解説しています。

SES現場での活用シーン

参画プロジェクトのAPI仕様理解

SESエンジニアが新しいプロジェクトに参画する際、APIドキュメントが不十分なケースは珍しくありません。

claude "このプロジェクトのAPI仕様を解析し、
以下の形式でドキュメント化してください：
1. エンドポイント一覧（メソッド・パス・認証要否）
2. リクエスト/レスポンスのサンプルJSON
3. エラーコードの一覧と対処法
4. 認証フローの説明図
新規参画者が30分で理解できるレベルの説明を付けてください。"

レガシーAPIのドキュメント化

ドキュメントのないレガシーAPIをClaude Codeで一気にドキュメント化するケースも増えています。

claude "このレガシーAPIの全エンドポイントをリバースエンジニアリングし、
OpenAPI仕様書を作成してください。
- 実装コードとテストコードの両方を分析
- データベーススキーマからレスポンス型を推論
- 暗黙のバリデーションルールを明文化
- 未ドキュメントのエラーパターンも洗い出す"

Claude Codeレガシーコード改善ガイドで、レガシーコード全般の改善手法も確認できます。

まとめ — Claude Codeでドキュメント負債をゼロにする

API開発におけるドキュメント管理は、手動では持続不可能です。Claude Codeを活用することで、ドキュメントの自動生成・品質管理・CI/CD連携を一気に実現できます。

本記事のポイントをまとめます。

• ✅ 既存コードからOpenAPI仕様書をリバースエンジニアリング自動生成
• ✅ TypeScript型定義からスキーマを自動推論して保守コストを削減
• ✅ スキーマファースト開発でフロント・バックエンドの並行開発を実現
• ✅ CI/CDパイプラインでドキュメントと実装の乖離をゼロに
• ✅ SES現場での参画初日からプロジェクト理解を加速

まずは小さなAPIプロジェクトでClaude Codeによるドキュメント自動生成を試してみてください。一度ワークフローを構築すれば、以後のメンテナンスはほぼ自動化できます。