README

API Platform Extra 将额外的功能或错误修复添加到 API Platform 中，这些功能尚未发布或不会发布。

安装

使用 composer 在 krak/api-platform-extra 中安装。

使用方法

默认情况下，此库提供的所有功能都是 opt-in，因此您需要显式地在配置中启用每个功能才能使用这些功能。

MessageBusDataPersister

默认启用消息总线数据持久化，并通过以下配置控制：

api_platform_extra:
    enable_message_bus_data_persister: true

MessageBusDataPersister 将将任何未由标准数据持久化程序处理的任何消息推送到消息总线。

因此，您需要做的就是简单地为要通过消息总线处理的 ApiPlatform 资源注册消息处理器。

额外的 Swagger 文档

这允许您将额外的 Swagger 文档合并并覆盖 API Platform 生成的 Swagger 文档。如果您需要在定义的 API Platform 资源之外提供任何自定义端点，则此功能非常有用。

定义 Swagger 文件的配置在此处

api_platform_extra:
    additional_swagger_path: "%kernel.project_dir%/config/api_platform/swagger.yaml"

如果该文件存在，将合并额外的 Swagger 文档。否则，将不会发生任何操作。

复数数据路径段名称生成器

默认情况下，API Platform 的屈折变换器会将任何以 Data 结尾的资源转换为 Datas。此修复了此特定用例，并且可能可以扩展以调整多个屈折修复。

构造函数反序列化器

该问题实际上已经修复，但仍在等待发布 api-platform/core#2178。此库将包含该补丁，直到 API Platform 2.4.0 发布。

这基本上允许您使用嵌套实体的构造函数参数，如下所示：

<?php

namespace App\Entity;

class Book
{
    private $id;
    private $name;
    private $author;
    private $createdAt;

    public function __construct(string $name, Author $author) {
        $this->name = $name;
        $this->author = $author;
        $this->createdAt = new \DateTime();
    }

    public function getId(): ?int {
        return $this->id;
    }

    public function getName(): string {
        return $this->name;
    }

    public function getAuthor(): Author {
        return $this->author;
    }

    public function getCreatedAt(): \DateTimeInterface {
        return $this->createdAt;
    }
}

实际的 POST API 请求将如下所示：

{
    "name": "Book Name!",
    "author": "/authors/1"
}

api_platform_extra:
    enable_constructor_deserialization: true

操作资源类

此功能由以下配置控制：

api_platform_extra:
    enable_operation_resource_class: true

启用后，此功能将允许您使用非常简单的配置定义每个操作的特定资源类。这对于在 POST 集合操作中想使用特殊的 DTO 资源而不是实际的实体资源特别有用。

以下是设置方法：

<?php

// under App\Entity
class Book
{
    private $id;
    private $name;
    private $author;

    public function __construct(string $name, Author $author) {
        // assign
    }
}

// under App\DTO
class CreateBookRequest
{
    public $name;
    public $authorName;

    public function __construct(string $name, string $authorName) {
        $this->name = $name;
        $this->authorName = $authorName;
    }
}

// under App\Service
class CreateBook
{
    public function __invoke(CreateBookRequest $req): Book {
        // use the req data to actually create then pesist/flush the Book instance
    }
}

然后，您可以使用以下 yaml 配置资源。您可以使用注解或 xml，但我发现使用 yaml 更容易管理：

App\Entity\Book:
  collectionOperations:
    get: ~
    post:
      resource_class: App\DTO\CreateBookRequest
App\DTO\CreateBookRequest:
  attributes:
    schema_only: true

这将确保文档和 API 使用 CreateBookRequest 的模式而不是正常的 Book 实体模式。使用 DTO 的 schema_only 属性确保不会为此资源生成任何路径。

您需要确保消息总线数据持久化已启用，以便正确地将请求连接到 CreateBook 服务。

仅定义资源

可能存在某些资源您只想用于定义，但使用自定义端点/ Swagger 文档，为此，您只需使用 schema_only: true 属性。

ApiProperty 覆盖

在 ApiProperty 注解中的任何定义都不会覆盖由 Serializer Property Metadata Factory 制作的更改。您可以使用以下选项来控制 ApiProperty 是否可以覆盖：

api_platform_extra:
    enable_overriding_annotation_property_metadata_factory: true