在 Api-Platform/OpenApi 中使用本机枚举

Question

我正在使用 Api-平台学习 OpenApi/Swagger API。我创建了一个新端点，它接受枚举值作为参数：

#[ApiResource(
itemOperations: [
    'get_by_name' => [
        'openapi_context' => [
            ....
            'parameters' => [
                [
                    'in' => 'header',
                    'name' => 'X-Server-Region',
                    'schema' => [
                    'type' => 'string',
                    'enum' => ['server1', 'server2'],
                    'example' => 'server1',
                 ],
                 'description' => 'Server to select',
                 'required' => true
             ],
...
)]

但是，这是一个相当常见的参数并且值可以经常更新（随着添加更多服务器），我想使用某种模板。

所以我尝试了：

<?php

namespace App\Enum;

enum Server: string
{
    case SERVER1 = 'server1';
    case SERVER2 = 'server2';
    ...
}

和

'enum' => [...Server::cases()],

或

'enum' => [Server::class],

以及许多其他形式，但无济于事。

我试图理解组件的概念，但找不到在 Symfony/Api 平台中使用它们的方法。

如何在不同端点重复使用枚举？

Answer 1

枚举对于 PHP 来说是相当新的，Api-Platform 尚不直接支持它们。

支持will come，但目前您必须在配置中手动明确列出每种情况。

虽然您也可以将 'cases' 的列表存储在 class 中的常量中（您甚至可以在 enum 本身中这样做）：

enum Server : string {
   const CASES = ['server1', 'server2']
   case SERVER1 = 'server1';
   case SERVER2 = 'server2';
}

然后直接在注释或属性中使用该常量：

parameters' => [
                [
                    'in' => 'header',
                    'name' => 'X-Server-Region',
                    'schema' => [
                    'type' => 'string',
                    'enum' => Server::CASES,
                    'example' => 'server1',
                 ],
                 'description' => 'Server to select',
                 'required' => true
             ],

...这不会真正利用枚举优势，因为您仍然需要在两个地方编辑案例，而不仅仅是一个；并且只对注释或属性方便。如果您为 API 资源使用 XML 或 YAML 配置，那就不会那么好。

Answer 2

要在 Enum 支持可用之前暂时解决问题，您可以使用数据原型创建一个 class，以便在 API 中重用它。这样您就可以重复使用相同的数据集而无需复制它。这将使您以后的工作变得更轻松。

因此您创建了这样的数据原型：

    class  Server
    {
        public const  PROTOTYPE = [ 'select1', 'select2', 'select3'];
    }

导入 calss 然后在你的注释中这样调用它：

'enum' => Server::PROTOTYPE,

在 Api-Platform/OpenApi 中使用本机枚举

Using Native Enum in Api-Platform / OpenApi

php

enums

symfony

api-platform.com

php-8.1