mcpField
A
api-platform-versioning

api-platform-versioning

github.com/dev-toolings開発22775 回インストール3 週間前に更新
リポジトリ

api-platform-versioning について

Symfony 向けのスキルで、API Platform のバージョニング戦略を選択し実装します。並行バージョンより非推奨化を優先し、サンセット通知、レスポンスヘッダー、文書化、テストを扱います。

主な機能

  1. 01リソースと操作の非推奨化設定
  2. 02サンセット日付とレスポンスヘッダーの追加
  3. 03必要に応じた並行URIバージョンの運用
  4. 04有効なバージョンの文書化とテスト

活用シーン

  1. 01APIフィールドや操作の改名・削除
  2. 02API削除までの期間の告知
  3. 03表現形式の破壊的変更への対応

インストール

コマンドをコピーしてターミナルで実行します。

$npx skills add https://github.com/dev-toolings/superpowers-symfony --skill api-platform-versioning

インストール後、Claude Code で/api-platform-versioningを入力して読み込まれたか確認します。

同梱ファイルreference.md

詳細

Api Platform Versioning (Symfony)

使用する場面

  • フィールド、操作、またはリソースの名前を変更または削除するため、利用者に移行期間が必要な場合。
  • Sunset ヘッダーと Deprecation ヘッダーを使って、クライアントに削除日を告知する場合。
  • 非推奨化と、並行する /v1 および /v2 のインターフェースのどちらにするかを決める場合。
  • 非推奨化やグループでは表現できない、互換性を破壊する表現の変更がある場合。

デフォルトのワークフロー

  1. まず非推奨化を試します。リソース、操作、または #[ApiProperty] に deprecationReason を設定します。
  2. 日付を指定した sunset: を追加し、v4 では RFC 9745 の Deprecation と rel="successor-version" を含む Link を headers に設定します。
  3. v4 より前のバージョンでは、KernelEvents::RESPONSE リスナーからそれらのヘッダーを出力します。
  4. それでも互換性が破壊される場合に限り、異なるグループを指定した並行する uriTemplate の値（/v1、/v2）を公開するか、バージョンごとに 1 つのプロバイダーを持つ出力 DTO を用意します。
  5. OpenAPI で古い操作を非推奨としてマークし、バージョンごとに変更を文書化して、有効なすべてのバージョンをテストします。

ガードレール

  • 非推奨化を優先します。パスによるバージョニングはデフォルトではなく、代替手段です。
  • 必ずサンセット日を設定し、有効なバージョンは最大 2～3 個に抑えます。
  • deprecationReason と sunset は v3 と v4 で安定していますが、RFC 9745 の headers オプションは v4 世代の機能です。インストール済みのバージョンで利用できることを確認してください。
  • 軽微な追加変更には、新しいバージョンではなくグループを使用します。

段階的な情報開示

  • 実行方針とリスク管理にはこのファイルを使用します。
  • 実装の詳細が必要な場合は、リファレンスを参照します。

出力要件

  • 選択した非推奨化またはバージョニングの戦略と、その理由。
  • 非推奨にする要素、サンセット日、および後継バージョンへのリンク。
  • 有効な各バージョンとヘッダーのテスト。

リファレンス

  • reference.md

コメント

Markdown 対応