如何在API Platform中禁用IRI要求，提交包含嵌套实体的完整记录

可以直接传入嵌套实体数据替代IRI，只需对关联实体做如下配置即可：

1. 配置级联操作与序列化组 #

在主实体的关联属性上添加级联持久化配置，同时将关联实体需要传入的字段和主实体使用同一组序列化/反序列化分组，示例如下：

// 主实体示例（以订单实体为例）
#[ApiResource(
    normalizationContext: ['groups' => ['order:read']],
    denormalizationContext: ['groups' => ['order:write']],
)]
class Order
{
    // 其他字段省略

    #[ORM\ManyToOne(targetEntity: Address::class, cascade: ['persist'])]
    #[Groups(['order:read', 'order:write'])]
    private $address;
}

// 关联实体示例（以收货地址实体为例）
class Address
{
    // 其他字段省略

    #[Groups(['order:read', 'order:write'])]
    private $province;

    #[Groups(['order:read', 'order:write'])]
    private $city;

    #[Groups(['order:read', 'order:write'])]
    private $detail;
}

cascade: ['persist']配置用于告知Doctrine自动持久化新创建的嵌套实体，如果需要支持更新嵌套实体，可将配置调整为cascade: ['persist', 'update']。

2. 关闭IRI验证 #

在关联属性上添加ApiProperty配置，告知框架允许直接写入嵌套对象而非强制校验IRI：

#[ORM\ManyToOne(targetEntity: Address::class, cascade: ['persist'])]
#[Groups(['order:read', 'order:write'])]
#[ApiProperty(readableLink: false, writableLink: true)]
private $address;

• writableLink: true：允许直接传入嵌套对象写入关联字段
• readableLink: false：接口返回数据时直接输出嵌套对象内容，如需返回IRI可将该值设为true

3. 集合类关联配置 #

如果是一对多、多对多的集合类型关联，配置逻辑完全一致，仅需将对应配置加到集合属性上即可，示例如下：

#[ORM\OneToMany(mappedBy: 'order', targetEntity: OrderItem::class, cascade: ['persist'])]
#[Groups(['order:read', 'order:write'])]
#[ApiProperty(readableLink: false, writableLink: true)]
private $orderItems;

异常排查 #

• 若出现Expected IRI报错：检查关联属性是否正确配置了writableLink: true
• 若出现嵌套字段不识别：检查嵌套实体的对应字段是否加入了主实体的反序列化分组
• 若出现关联实体未找到报错：检查关联属性是否配置了正确的级联操作

内容的提问来源于stack exchange，提问作者bglevon