api-platform-serialization

Api Platform Serialization（Symfony）

使用する場面

• オペレーションごとに異なるフィールド（一覧、読み取り、作成、更新）を公開する必要がある場合。
• 関連リソースを IRI として表示するか、埋め込み表示する必要がある場合。
• 計算フィールドやロールに応じたフィールドをレスポンスに含める必要がある場合。
• 日付形式などのノーマライザーオプションをプロパティに設定する必要がある場合。

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

1. グループに entity:operation という名前を付け、オペレーションごとに normalizationContext と denormalizationContext を設定します。
2. 古い Annotation ではなく、Serializer の Attribute 名前空間にある #[Groups] でプロパティを指定します。
3. #[ApiProperty(readableLink: false, writableLink: false)] を使ってリレーションを制御し、IRI を強制します。
4. ノーマライザーを作成する代わりに、#[Context] でプロパティごとのオプションを適用します。
5. カスタムノーマライザーに計算フィールドを追加し、api_platform.serializer.context_builder のデコレーターに動的なグループを追加します。
6. #[MaxDepth] と enable_max_depth で循環を防ぎ、#[Ignore] で機密情報を隠します。

ガードレール

• 読み取り用と書き込み用のグループを分けます。たとえば、password は作成グループのみに、id は読み取りグループのみに含めます。
• 関連リソースは、親と同じグループを共有する場合にのみ埋め込み表示され、それ以外の場合は IRI として表示されます。
• コンテキストで enable_max_depth が true でない限り、#[MaxDepth] は効果がありません。
• エンティティをシンプルに保ちます。計算フィールドはノーマライザーに追加します。

段階的な情報開示

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

出力要件

• フィールドマトリクスとして、オペレーションごとのグループとコンテキストを示します。
• 追加したノーマライザーまたはコンテキストビルダーと、その登録方法を示します。
• 結果のフィールドを示すテストまたは OpenAPI 出力を提示します。

リファレンス

• reference.md