Api Platform自定义公开API端点相关技术问询

我是Api Platform的新手，目前很难找到实现功能所需的全部文档。我需要创建一个公开端点，用于获取移动应用的当前版本号（该版本号仅为一个存储的字符串）。

截至目前，我基于网络资料、官方文档、示例及SymfonyCast教程，在/Entity目录下创建了名为PublicApi的PHP实体类：

use Ramsey\Uuid\Uuid;

#[ApiResource(
    collectionOperations: [],
    itemOperations: [
        'version' => [
            'method'     => 'GET',
            'read'       => false,
            'write'       => false,
            'path'       => '/version',
            'controller' => ApiPublicVersionAction::class,
            "openapi_context"         => [
                "summary"     => "Returns current app version.",
                "description" => "Public endpoint, no need to authenticate",
                'parameters'  => [],
                'requestBody' => [],
            ],
        ],
    ],
    routePrefix: '/public'
)]
class PublicApi {
    
    #[ApiProperty( identifier: true )]
    public $code;
    
    #[ApiProperty]
    private string $exposedData;
    
    public function __construct() {
        $this->code = Uuid::uuid4();
    }
}

该路由已被Api Platform识别，可在文档中查看并测试。对应的控制器仅包含__invoke方法：

<?php

namespace App\Controller\Api;

use App\Entity\PublicApi;
use Symfony\Bundle\FrameworkBundle\Controller\AbstractController;

class ApiPublicVersionAction extends AbstractController {
    
    public function __invoke() {
        return ( new PublicApi() )->setExposedData( '1.0.0' );
    }
}

虽然该实现可正常运行，但我仍存在诸多困惑，现提出以下技术疑问：

1. 创建自定义公开端点是否必须为每个端点创建仅含__invoke方法的独立控制器？有无其他实现方式？
2. 能否使用单个控制器处理所有端点，让Api Platform调用对应的方法？
3. collectionOperations、itemOperations和openapi_context支持哪些配置选项？
4. 为何在无需获取数据、仅返回非结构化数据的场景下，仍必须设置标识符？当前实现要求传入随机字符串作为标识符，但实际并无此需求。
5. 此场景下是否需要使用DataProvider？我测试创建了一个简单的DataProvider，但未获得实际收益，反而增加了维护成本。

问题解答 #

1. 是否必须为每个自定义端点创建独立的__invoke控制器？ #

不是必须的。除了独立控制器，还有两种更灵活的方式：

• 直接使用闭包：简单逻辑可以直接把代码写在ApiResource的操作配置里，省去单独的控制器类：

  'version' => [
      'method' => 'GET',
      'read' => false,
      'write' => false,
      'path' => '/version',
      'controller' => function() {
          $publicApi = new PublicApi();
          $publicApi->setExposedData('1.0.0');
          return $publicApi;
      },
      // ...openapi_context配置
  ]
  

• 复用Action类：如果多个端点逻辑有共性，可以创建包含多个方法的类，结合配置指定调用的方法。

2. 能否用单个控制器处理所有端点？ #

完全可以。你可以创建一个包含多个业务方法的控制器类，然后在ApiResource的操作配置里指定控制器类+方法名的组合：

示例控制器：

namespace App\Controller\Api;

use App\Entity\PublicApi;
use Symfony\Bundle\FrameworkBundle\Controller\AbstractController;

class PublicApiController extends AbstractController {
    public function getVersion() {
        $publicApi = new PublicApi();
        $publicApi->setExposedData('1.0.0');
        return $publicApi;
    }

    public function getAppStatus() {
        // 另一个公开端点的逻辑
    }
}

对应的ApiResource配置：

'collectionOperations' => [
    'version' => [
        'method' => 'GET',
        'read' => false,
        'write' => false,
        'path' => '/version',
        'controller' => [PublicApiController::class, 'getVersion'],
        // ...openapi配置
    ],
    'status' => [
        'method' => 'GET',
        'read' => false,
        'write' => false,
        'path' => '/status',
        'controller' => [PublicApiController::class, 'getAppStatus'],
        // ...openapi配置
    ],
]

3. collectionOperations、itemOperations和openapi_context的配置选项 #

• collectionOperations/itemOperations核心配置：

  • method：指定HTTP请求方法（GET/POST/PUT/PATCH/DELETE等）
  • path：自定义路由路径
  • controller：处理请求的控制器、闭包或[类, 方法名]组合
  • read：是否启用数据读取流程（设为false跳过DataProvider等环节）
  • write：是否启用数据写入流程（设为false跳过DataPersister等环节）
  • security：Symfony表达式，用于权限控制
  • security_message：权限验证失败的提示信息
  • normalization_context：序列化上下文（比如指定序列化组）
  • denormalization_context：反序列化上下文
  • openapi_context：OpenAPI文档自定义配置

• openapi_context常见配置：

  • summary：端点简短描述
  • description：端点详细说明
  • parameters：自定义请求参数列表
  • responses：自定义响应状态码和响应体定义
  • tags：给端点打标签，用于文档分类
  • security：指定认证方式（空数组表示无需认证）

4. 为何必须设置标识符？ #

因为你当前把端点定义成了item操作，Api Platform的item操作默认绑定单个资源实例，所以要求实体有标识符。但你的场景不需要定位具体资源，换成collection操作就能解决这个问题：

修改ApiResource配置，把版本端点移到collectionOperations中，同时可以移除实体里的标识符字段：

#[ApiResource(
    collectionOperations: [
        'version' => [
            'method' => 'GET',
            'read' => false,
            'write' => false,
            'path' => '/version',
            'controller' => ApiPublicVersionAction::class,
            'openapi_context' => [
                "summary" => "Returns current app version.",
                "description" => "Public endpoint, no need to authenticate",
            ],
        ],
    ],
    itemOperations: [],
    routePrefix: '/public'
)]
class PublicApi {
    #[ApiProperty]
    private string $exposedData;

    // 省略标识符相关代码
}

5. 此场景是否需要DataProvider？ #

不需要。DataProvider的作用是从数据库、外部API等数据源读取资源数据，而你的场景只是返回固定的版本字符串，完全不需要读取外部数据。直接用控制器返回数据更简单，避免额外的维护成本。

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