使用 api 平台为 Symfony 自定义控制器生成 OpenAPI

Question

我刚刚开始使用 Symfony (7.1) 并创建了一个控制器。 现在我想为控制器端点生成 OpenAPI 描述，我已经找到了 api_platform (4.0)。 （https://api-platform.com/docs/core/controllers/）

我安装了 api_platform 包但无法运行。 如果可能的话，我想使用 BlocDto 中定义的属性将响应定义为 json。

要使其正常工作还缺少什么，或者这是不可能的？

控制器。 （当我省略默认值时，端点可以工作。）

<?php

namespace App\Controller;

use App\DTO\BlocDto;
use App\Repository\BlocRepository;
use Symfony\Bundle\FrameworkBundle\Controller\AbstractController;
use Symfony\Component\HttpFoundation\JsonResponse;
use Symfony\Component\Routing\Attribute\Route;

class BlocsController extends AbstractController
{
    private $blocRepository;
    public function __construct(BlocRepository $blocRepository)
    {
        $this->blocRepository = $blocRepository;
    }

    #[Route(
      path: '/blocs/{id}',
      name: 'get-bloc',
      methods: ['GET', 'HEAD'],
      defaults: [
        '_api_resource_class' => BlocDto::class,
        '_api_operation_name' => 'getBloc'
      ])]
    public function getBloc($id): JsonResponse
    {
        $bloc = $this->blocRepository->find($id);

        return $this->json([
          'id' => $bloc->getId(),
          'name' => $bloc->getName(),
          'description' => $bloc->getDescription(),
          'blocLowRes' => $bloc->getBlocLowRes(),
          'blocMedRes' => $bloc->getBlocMedRes(),
          'blocHighRes' => $bloc->getBlocHighRes(),
        ]);
    }
}

BlocDto.php

<?php

namespace App\DTO;

use Symfony\Component\Validator\Constraints as Assert;

class BlocDto
{
    public function __construct(
      #[Assert\NotBlank]
      public string $id,

      #[Assert\NotBlank]
      public string $name,

      public string $description,

      public string $blocLowRes,

      public string $blocMedRes,

      public string $blocHighRes)
    { }
}

显然 config/packages/api_platform.yaml 应该如下所示：

api_platform:
    title: Boulder Api
    version: 1.0.0
    use_symfony_listeners: true
    defaults:
        stateless: true
        cache_headers:
            vary: ['Content-Type', 'Authorization', 'Origin']

Answer 1

API平台主要是为了自动化实体的API而构建的。因此，它不是最适合自定义构建 API 的文档，但它应该可以工作。

API Platform基于实体工作。为其构建 BlocDto 的实体 Bloc 应标记为 ApiResource。然后在 Get() 端点定义中向 API 平台提供有关路由和 Dto 的信息。

我不能 100% 确定 Get() 端点需要哪个参数，因为我只使用 Post() 端点和 Dto 端点。但这应该是一个很好的起点。

<?php

namespace App\Entity;

use Doctrine\ORM\Mapping as ORM;
use ApiPlatform\Metadata\ApiResource;
use ApiPlatform\Metadata\Get;
use App\Controller\BlocsController;
use App\DTO\BlocDto;

#[ORM\Entity()]
#[ApiResource(
    operations: [
        new Get(uriTemplate: 'bloc/{id}', routeName: 'get-bloc', output: BlocDto::class, outputFormat: 'json')
    ]
)]
class Bloc
{
    ...
}

有关更多信息，请参阅 API 平台文档中的使用数据传输对象和操作。