CR-FASTAPI-012: SDK 自動生成導線の構築 - 完了レポート

実装日時

2024年12月4日

概要

目的

FastAPI 移行（CR-FASTAPI-001〜010A）により /api/v1/* が NexusCore の唯一の Public API となったため、OpenAPI 仕様書を元に Python / TypeScript 向け SDK を自動生成できる導線を追加しました。

ゴール

  • SDK 自動生成スクリプトの作成（tools/generate_sdk.py）
  • Makefile / CLI 導線の追加（make sdk, make sdk-python, make sdk-ts）
  • docs/api/README.md に SDK 生成手順を追加
  • .cursorrules に SDK 破壊検証ルールを追加
  • 完了レポート作成

原則

  • OpenAPI generator の基本出力のままで可（カスタマイズは後続 CR で扱う）
  • SDK 生成スクリプトの破壊的変更は禁止
  • FastAPI API の変更時は、SDK が正しく生成できることを確認すること

実装ステップ

Step 1: Spec の作成

実施内容:

  • docs/spec/CR-FASTAPI-012_SDK_Auto_Generation.md を作成
  • CR-NEXUS-SPEC-STANDARDIZATION のルールに従い、実装前に Spec を作成

結果:

  • ✅ Spec を作成しました

Step 2: SDK ディレクトリの作成

実施内容:

  • sdk/python/ ディレクトリを作成
  • sdk/typescript/ ディレクトリを作成
  • sdk/.gitkeep を作成

結果:

  • ✅ SDK ディレクトリを作成しました

Step 3: SDK 自動生成スクリプトの作成

新規作成ファイル: tools/generate_sdk.py

実装内容:

  • OpenAPI 仕様書の取得（URL またはファイルから）
  • openapi-generator-cli の検出（npx または Java 版）
  • Python SDK の生成（sdk/python/ に出力）
  • TypeScript SDK の生成（sdk/typescript/ に出力）
  • 生成結果の検証（主要ファイルの存在確認）

主な機能:

  • --python: Python SDK のみ生成
  • --typescript: TypeScript SDK のみ生成
  • --all: すべての SDK を生成（デフォルト）
  • --openapi-url: OpenAPI JSON の URL を指定
  • --openapi-file: OpenAPI JSON ファイルのパスを指定

結果:

  • ✅ SDK 自動生成スクリプトを作成しました

Step 4: Makefile コマンドの追加

変更ファイル: Makefile

追加内容:

  • make sdk: すべての SDK を生成
  • make sdk-python: Python SDK のみ生成
  • make sdk-ts: TypeScript SDK のみ生成

結果:

  • ✅ Makefile に SDK 生成コマンドを追加しました

Step 5: ドキュメント更新

変更ファイル: docs/api/README.md

追加内容:

  • CR-FASTAPI-012 の完了を追記
  • SDK 自動生成セクションを追加
    • 前提条件
    • Python SDK の生成方法
    • TypeScript SDK の生成方法
    • すべての SDK を生成
    • 生成物の活用例（Python / TypeScript）

結果:

  • ✅ docs/api/README.md を更新しました

Step 6: .cursorrules の更新

変更ファイル: .cursorrules

追加内容:

  • SDK Auto-Generation Rules (SDK 自動生成ルール) セクションを追加
    • SDK 自動生成導線の維持
    • SDK 生成の必須要件
    • SDK 生成の検証

結果:

  • ✅ .cursorrules を更新しました

Step 7: .gitignore の更新

変更ファイル: .gitignore

追加内容:

  • sdk/python/ を除外
  • sdk/typescript/ を除外
  • sdk/.gitkeep は除外しない

結果:

  • ✅ .gitignore を更新しました

変更ファイル一覧

新規作成ファイル

  • docs/spec/CR-FASTAPI-012_SDK_Auto_Generation.md - Spec
  • tools/generate_sdk.py - SDK 自動生成スクリプト
  • sdk/.gitkeep - SDK ディレクトリの保持ファイル
  • docs/api/CR-FASTAPI-012_完了報告.md - 本完了レポート

変更ファイル

  • Makefile - SDK 生成コマンドを追加
  • docs/api/README.md - SDK 生成手順を追加
  • .cursorrules - SDK Auto-Generation Rules を追加
  • .gitignore - SDK 生成物を除外

新規作成ディレクトリ

  • sdk/python/ - Python SDK の出力先
  • sdk/typescript/ - TypeScript SDK の出力先

動作確認結果

静的解析結果

  • リンターエラー: なし
  • 型チェック: 問題なし

スクリプトの動作確認

確認コマンド:

python tools/generate_sdk.py --help

確認結果:

  • ✅ スクリプトが正常に動作することを確認
  • ✅ ヘルプメッセージが正しく表示されることを確認

注意: 実際の SDK 生成には、FastAPI アプリが起動している必要があります。

Makefile コマンドの確認

確認コマンド:

make help

確認結果:

  • ✅ make sdk, make sdk-python, make sdk-ts がヘルプに表示されることを確認

ドキュメントの確認

確認項目:

  1. ✅ docs/api/README.md に SDK 生成手順が追加されているか
  2. ✅ .cursorrules に SDK Auto-Generation Rules が追加されているか
  3. ✅ .gitignore に SDK 生成物が除外されているか

確認結果:

  • ✅ すべての項目が確認できました

設計上の改善点

アーキテクチャの改善

  1. SDK 自動生成導線の構築
    • OpenAPI 仕様書を元に SDK を自動生成できる仕組みを構築
    • Makefile コマンドで簡単に SDK を生成できるように
  2. 検証機能の内蔵
    • 生成された SDK の主要ファイルの存在確認を自動化
    • 生成結果の検証をスクリプトに内蔵

将来の拡張性への配慮

  1. SDK カスタマイズ
    • 現在は OpenAPI generator の基本出力を使用
    • 将来的にはカスタマイズオプションを追加可能
  2. CI/CD 統合
    • SDK 生成スクリプトは CI/CD に統合可能な設計
    • 後続 CR で CI/CD の自動配布機能を追加予定
  3. PyPI/npm 公開
    • 生成された SDK を PyPI/npm に公開する機能は後続 CR で実装予定

コード品質の向上

  1. 明確なエラーハンドリング
    • openapi-generator-cli が利用できない場合の明確なエラーメッセージ
    • OpenAPI 仕様書の取得失敗時の適切なエラーハンドリング
  2. 柔軟な設定
    • OpenAPI URL またはファイルパスを指定可能
    • Python / TypeScript を個別に生成可能

既知の制約・注意事項

既存コードとの互換性

  • ✅ 既存のコードに影響なし
  • ✅ SDK 生成スクリプトは独立したツール

制限事項やトレードオフ

  1. openapi-generator-cli の依存
    • SDK 生成には openapi-generator-cli が必要
    • npm 経由または Java 版をインストールする必要がある
  2. FastAPI アプリの起動が必要
    • SDK 生成時は FastAPI アプリが起動している必要がある
    • または OpenAPI JSON ファイルを直接指定可能
  3. SDK のカスタマイズ
    • 現在は OpenAPI generator の基本出力を使用
    • カスタマイズは後続 CR で実装予定

移行時の注意点

  • SDK を再生成する場合は、既存の SDK ディレクトリを削除してから実行してください
  • FastAPI API の仕様が変更された場合は、SDK を再生成する必要があります

次のステップ

推奨されるフォローアップアクション

  1. SDK の実際の生成と検証
    • FastAPI アプリを起動して SDK を実際に生成
    • 生成された SDK が正しく動作することを確認
  2. CI/CD 統合
    • SDK 生成を CI/CD パイプラインに統合
    • API 仕様変更時に自動的に SDK を再生成
  3. PyPI/npm 公開
    • 生成された SDK を PyPI/npm に公開する機能を実装
    • バージョン管理とリリースプロセスの確立
  4. SDK カスタマイズ
    • OpenAPI generator の設定をカスタマイズ
    • プロジェクト固有の設定を追加

関連ドキュメント

まとめ

CR-FASTAPI-012 の実装により、SDK 自動生成導線の構築を完了しました。OpenAPI 仕様書を元に Python / TypeScript 向け SDK を自動生成できるスクリプト（tools/generate_sdk.py）を作成し、Makefile コマンド（make sdk, make sdk-python, make sdk-ts）を追加しました。また、docs/api/README.md に SDK 生成手順を追加し、.cursorrules に SDK Auto-Generation Rules を追加しました。

すべての変更が完了し、SDK 自動生成導線が構築されました。

This site uses Just the Docs, a documentation theme for Jekyll.