CR-FASTAPI-012A: SDK Generator Tooling Hardening（ツール固定＋安全テスト追加）- 完了レポート

実装日時

2024年12月5日

概要

目的

CR-FASTAPI-012 で構築された SDK 自動生成導線（tools/generate_sdk.py）を、長期運用時に壊れにくくするための「ハードニング」を実施しました。

ゴール

  1. SDK 生成に使うツールとバージョンを明示し、依存関係として固定する
  2. tools/generate_sdk.py が壊れていないことを確認する最小限の pytest を追加する
  3. Spec、README、.cursorrules に反映し、「SDK 生成の運用ルール」として一貫させる

原則

  • 既存の実装（CR-FASTAPI-012）を壊さない
  • 軽量テストのみ追加（実際の SDK 生成は行わない）
  • ツールのバージョン情報を明示し、長期運用時のブレを防ぐ

実装ステップ

Step 1: Spec の作成

実施内容:

  • docs/spec/CR-FASTAPI-012A_SDK_Tooling_Hardening.md を作成
  • CR-FASTAPI-012 の前提を確認し、今回のハードニング内容を明確化

結果:

  • ✅ Spec を作成しました

Step 2: 使用ツールの確認とドキュメント化

実施内容:

  • tools/generate_sdk.py を確認し、実際に使用しているツールを特定
  • 結果: @openapitools/openapi-generator-cli（npx 経由または Java 版）
  • Spec にツール名と推奨バージョンを明記

結果:

  • ✅ 使用ツールを特定し、ドキュメント化しました

Step 3: 安全性テストの追加

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

実装内容:

  • tools/generate_sdk.py が正常に import できることを確認するテスト
  • --help オプションが正常に動作することを確認するテスト
  • check_openapi_generator() 関数が正常に動作することを確認するテスト（subprocess はモック）
  • モジュールに必要な関数が存在することを確認するテスト

主なテストケース:

  • test_generate_sdk_import(): モジュールの import が成功すること
  • test_generate_sdk_help_runs(): --help オプションが正常に動作すること
  • test_check_openapi_generator_mocked(): check_openapi_generator() が正常に動作すること（subprocess はモック）
  • test_check_openapi_generator_not_available(): openapi-generator が見つからない場合を正しく処理すること
  • test_generate_sdk_module_has_required_functions(): 必要な関数が存在することを確認

結果:

  • ✅ 安全性テストを追加しました

Step 4: ドキュメント更新

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

追加内容:

  • 「SDK 自動生成」セクションを追加
    • 前提条件（使用ツールとバージョン情報）
    • SDK 生成方法（make sdk, make sdk-python, make sdk-ts）
    • 生成物の場所
    • 生成物の活用例（Python / TypeScript）
    • 注意事項

結果:

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

Step 5: README.md の更新

変更ファイル: README.md

追加内容:

  • 「SDK 自動生成」セクションを追加
    • OpenAPI 仕様書から SDK を自動生成できることの説明
    • SDK コードは手書きせず、必ず tools/generate_sdk.py を使用することの明記
    • OpenAPI 仕様書が SDK の単一のソース（Single Source of Truth）であることの明記

結果:

  • ✅ README.md を更新しました

Step 6: .cursorrules の更新

変更ファイル: .cursorrules

追加内容:

  • 「SDK Auto-Generation Rules」セクションを拡張
    • SDK 生成ツールの固定化（CR-FASTAPI-012A）セクションを追加
    • SDK コードの手書き禁止ルールを追加
    • SDK 生成スクリプトの変更ルールを追加

結果:

  • ✅ .cursorrules を更新しました

変更ファイル一覧

新規作成ファイル

  • docs/spec/CR-FASTAPI-012A_SDK_Tooling_Hardening.md - Spec
  • tests/tools/test_generate_sdk_safe.py - SDK 生成スクリプトの安全性テスト
  • docs/api/CR-FASTAPI-012A_完了報告.md - 本完了レポート

変更ファイル

  • docs/api/README.md - SDK 自動生成セクションを追加
  • README.md - SDK 自動生成セクションを追加
  • .cursorrules - SDK Auto-Generation Rules を拡張

動作確認結果

静的解析結果

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

テスト実行結果

確認コマンド:

python -m pytest tests/tools/test_generate_sdk_safe.py -q -v

確認結果:

============================= test session starts ==============================
platform linux -- Python 3.12.3, pytest-7.4.4, pluggy-1.4.0
rootdir: /home/yn441611/NexusCore
configfile: pytest.ini
collected 5 items

tests/tools/test_generate_sdk_safe.py .....                              [100%]

============================== 5 passed in 0.22s ===============================
  • ✅ すべてのテストが成功しました（5 passed）
  • ✅ 実行時間: 0.22秒（軽量テストとして適切）

SDK 生成スクリプトの動作確認

確認コマンド:

python tools/generate_sdk.py --help

確認結果:

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

ドキュメントの確認

確認項目:

  1. ✅ docs/api/README.md に SDK 自動生成セクションが追加されているか
  2. ✅ README.md に SDK 自動生成セクションが追加されているか
  3. ✅ .cursorrules に SDK Auto-Generation Rules が拡張されているか
  4. ✅ docs/spec/CR-FASTAPI-012A_SDK_Tooling_Hardening.md が作成されているか

確認結果:

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

設計上の改善点

アーキテクチャの改善

  1. SDK 生成ツールの固定化
    • 使用ツール（@openapitools/openapi-generator-cli）と推奨バージョンを明示
    • 長期運用時のブレを防ぐためのドキュメント化
  2. 安全性テストの追加
    • tools/generate_sdk.py が壊れていないことを確認する軽量テストを追加
    • 実際の SDK 生成は行わず、import と基本的な関数呼び出しのみを検証
  3. 運用ルールの明確化
    • SDK コードの手書き禁止ルールを明文化
    • OpenAPI 仕様書が SDK の単一のソース（Single Source of Truth）であることを明記

将来の拡張性への配慮

  1. CI/CD 統合
    • SDK 生成スクリプトの安全性テストは CI/CD に統合可能な設計
    • 後続 CR で CI/CD の自動検証機能を追加予定
  2. E2E テスト
    • 現在は軽量テストのみ追加
    • 将来的には実際の SDK 生成を行う E2E テストを追加可能（別 CR として検討）
  3. ツールのバージョン管理
    • 現在は推奨バージョンを明記
    • 将来的にはバージョンを固定する仕組みを追加可能（別 CR として検討）

コード品質の向上

  1. 明確なテスト方針
    • 軽量テストのみ追加（実際の SDK 生成は行わない）
    • subprocess はモックして、呼び出し自体が行われることだけを検証
  2. ドキュメントの一貫性
    • Spec、README、.cursorrules を一貫性を持って更新
    • 「SDK 生成の運用ルール」として明確化

既知の制約・注意事項

既存コードとの互換性

  • ✅ 既存のコードに影響なし
  • ✅ SDK 生成スクリプトの既存機能は維持

制限事項やトレードオフ

  1. 外部ツールの依存
    • SDK 生成には @openapitools/openapi-generator-cli が必要
    • npm 経由または Java 版をインストールする必要がある
    • Python の requirements には追加できない（外部 CLI ツールのため）
  2. テストの範囲
    • 現在は軽量テストのみ追加（実際の SDK 生成は行わない）
    • E2E テストは別 CR として検討
  3. バージョンの固定
    • 現在は推奨バージョンを明記
    • バージョンを完全に固定する仕組みは別 CR として検討

移行時の注意点

  • SDK 生成スクリプトの変更時は、必ず Spec の更新を伴うこと
  • SDK コードの手書きは絶対禁止（OpenAPI 仕様書から自動生成すること）

次のステップ

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

  1. E2E テストの追加
    • 実際の SDK 生成を行う E2E テストを追加
    • FastAPI アプリを起動して SDK を実際に生成し、検証する
  2. CI/CD 統合
    • SDK 生成スクリプトの安全性テストを CI/CD パイプラインに統合
    • API 仕様変更時に自動的に SDK 生成スクリプトが壊れていないことを確認
  3. バージョン固定の仕組み
    • ツールのバージョンを完全に固定する仕組みを追加
    • 例: .nvmrc や package.json を使用してバージョンを固定
  4. SDK 生成の自動化
    • API 仕様変更時に自動的に SDK を再生成する仕組みを追加
    • CI/CD パイプラインに統合

関連ドキュメント

まとめ

CR-FASTAPI-012A の実装により、SDK 生成ツールの固定化と安全性テストの追加を完了しました。使用ツール（@openapitools/openapi-generator-cli）と推奨バージョンを明示し、tools/generate_sdk.py が壊れていないことを確認する軽量テストを追加しました。また、Spec、README、.cursorrules を一貫性を持って更新し、「SDK 生成の運用ルール」として明確化しました。

すべての変更が完了し、SDK 生成導線のハードニングが完了しました。

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