API Platform ApiResource注解OpenAPI规范提取失效问题求助

针对API Platform 3.2.4 + Symfony 6.2.14环境下，替代已废弃的openapi_context、将OpenAPI规范提取到独立类但未生效的问题，核心原因是openapi参数不支持直接传入类名，仅接受bool、Operation实例或可被容器解析的可调用服务。以下是两种可行解决方案：

方案1：直接实例化调用（无依赖场景） #

如果你的OpenAPI构建逻辑不需要依赖其他服务，可直接实例化自定义类并调用其__invoke方法，生成Operation实例传入参数：

#[ApiResource(
    shortName: 'Demande',
    operations: [
        new Get(
            openapi: (new PostDemandeOpenapi())(),
            provider: DemandeItemProvider::class
        ),
        // 其他操作
    ]
)]
final class DemandeResource {
    // ...
}

方案2：服务引用（推荐，支持依赖注入） #

若需要在OpenAPI构建逻辑中注入依赖（如配置、翻译服务等），需将自定义类注册为Symfony服务（开启autoconfigure后，src目录下的类会自动注册），然后通过服务ID引用：

1. 调整资源类注解 #

使用@服务完整类名的格式引用自定义OpenAPI类：

#[ApiResource(
    shortName: 'Demande',
    operations: [
        new Get(
            openapi: '@App\OpenApi\PostDemandeOpenapi',
            provider: DemandeItemProvider::class
        ),
        // 其他操作
    ]
)]
final class DemandeResource {
    // ...
}

2. 完善自定义OpenAPI类 #

确保类的__invoke方法正确返回\ApiPlatform\OpenApi\Model\Operation实例，可使用Operation::builder()简化构建：

namespace App\OpenApi;

use ApiPlatform\OpenApi\Model\Operation;
use ApiPlatform\OpenApi\Model\Parameter;
use ApiPlatform\OpenApi\Model\Response;

final class PostDemandeOpenapi
{
    // 可注入依赖，比如：
    // public function __construct(private readonly SomeService $someService) {}

    public function __invoke(): Operation
    {
        return Operation::builder()
            ->summary('获取单个请求详情')
            ->description('返回指定ID的Demande资源详情')
            ->addParameter(new Parameter(
                name: 'id',
                in: 'path',
                required: true,
                schema: ['type' => 'integer']
            ))
            ->addResponse(new Response(response: '200', description: '成功返回资源'))
            ->addResponse(new Response(response: '404', description: '资源不存在'))
            ->build();
    }
}

关键注意事项 #

• 必须确保返回的是\ApiPlatform\OpenApi\Model\Operation实例，注意命名空间不要混淆；
• 若使用服务引用，需确认Symfony容器能正确解析该服务（开启autoconfigure即可自动处理）；
• 避免直接传入类名（如PostDemandeOpenapi::class），API Platform无法识别此类格式的参数。

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