API 仕様書ジェネレータ

コース構成

このコースで学ぶこと

1. 01

   テストが一番正確な仕様

   ドキュメントは陳腐化するが、テストは常に最新。テストから OpenAPI を生成すれば、ドキュメントが嘘をつかなくなる。

   API ドキュメントは『書く時に正しい』が、コードが変わると古くなります。逆に、テストはコードと一緒に変わるので常に正しい。

   Claude Code に統合テストを読ませて OpenAPI スキーマを生成すれば、テスト = ドキュメントとなり、陳腐化が防げます。

   対象テストの書き方
2. 02

   対象テストの書き方

   OpenAPI 生成しやすいテストには『型ヒント・正常系・エラー系・実 HTTP』の 4 要素がある。

   • リクエスト型がコードから推測できる
   • 正常系 (200, 201) のレスポンス例
   • エラー系 (400, 401, 403, 404) のレスポンス例
   • 実 HTTP（superagent / fetch）で叩いている

   typescript

   describe("POST /api/users", () => {
     it("creates a user", async () => {
       const res = await fetch("/api/users", {
         method: "POST",
         body: JSON.stringify({ email: "x@y.com", name: "X" }),
       });
       expect(res.status).toBe(201);
       const body = await res.json();
       expect(body).toEqual({ id: expect.any(String), email: "x@y.com", name: "X" });
     });
   
     it("returns 400 if email missing", async () => {
       const res = await fetch("/api/users", { method: "POST", body: "{}" });
       expect(res.status).toBe(400);
     });
   });

   テストが一番正確な仕様プロンプトテンプレ：OpenAPI 生成
3. 03

   プロンプトテンプレ：OpenAPI 生成

   tests/api/ 配下を読んで、openapi.yaml を生成。

   text

   > tests/api/ 配下の全テストを読み、OpenAPI 3.1 仕様書を生成。
   
   ## 抽出する情報
   - エンドポイント（path + method）
   - リクエストパラメータ（query / path / body）
   - リクエスト body の型
   - レスポンス（status code 別）
   - レスポンス body の型
   - エラー例
   
   ## 出力
   - docs/openapi.yaml
   - info: 弊社の API 名・バージョン（CLAUDE.md から）
   - security: 認証方式（CLAUDE.md から）
   - 各エンドポイントに summary（テスト名から推測）
   - 各レスポンスに example（テストの期待値から）
   
   ## ルール
   - テストに無い情報は省略（推測しない）
   - 推測が必要な箇所は yaml の x-fixme コメントで明示

   出力イメージdocs/openapi.yaml の抜粋

   paths:
     /api/users:
       post:
         summary: ユーザーを作成する
         requestBody:
           content:
             application/json:
               schema:
                 type: object
                 properties:
                   email: { type: string }
         responses:
           "201": { description: 作成成功 }
           "400": { description: email 欠落 }
   …（テストから 12 エンドポイントを抽出）

   対象テストの書き方公開ドキュメントの自動化
4. 04

   公開ドキュメントの自動化

   OpenAPI → Redoc / Swagger UI で公開、CI で毎マージ更新。

   yaml

   # .github/workflows/api-docs.yml
   name: API Docs
   on:
     push:
       branches: [main]
   jobs:
     generate:
       runs-on: ubuntu-latest
       steps:
         - uses: actions/checkout@v4
         - uses: anthropics/claude-code-action@v1
           with:
             anthropic-api-key: ${{ secrets.ANTHROPIC_API_KEY }}
             prompt: |
               /api-docs-gen を実行して、docs/openapi.yaml を最新化。
               既存と差分があれば PR を作成。

   プロンプトテンプレ：OpenAPI 生成Skill 化と継続運用
5. 05

   Skill 化と継続運用

   ドキュメントは『一度書いて終わり』にしないのが鍵。

   手を動かす

   0 / 4

   • 上記プロンプトを `.claude/skills/api-docs-gen/SKILL.md` に
   • テストを増やすたびに自動でドキュメント更新
   • 外部開発者向けの公開ページ（Redoc）を立ち上げ
   • ドキュメントが古い箇所を検出する Skill も追加

   理解度チェック

   1. Q1.テストから OpenAPI を生成するアプローチが『ドキュメント陳腐化』を防げる理由は？

      Aドキュメントを月次で手動更新するからBテストはコードと一緒に変わるので常に最新、テスト = ドキュメントの一致が保たれるCAI がドキュメントを書き直すからDドキュメントを廃止できるから

   2. Q2.AI が生成した OpenAPI 仕様書を外部公開する前に、人間が必ず確認すべきは？

      Aファイル拡張子B認証要件・レート制限・サンプル値に内部 ID や PII が混入していないかCClaude のバージョンDロゴ画像の色

   3. Q3.API 仕様書ジェネレータの入力として最も適切なものは？

      AAPI のテストコード、ルート定義、CLAUDE.md にある外部公開ポリシーと命名規則BPOS の売上 CSVCSlack の DM 履歴D個人 SNS のフォロワー一覧
   公開ドキュメントの自動化