在 Api 平台 / 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],

以及其中的許多其他 forms，但無濟於事。

我試圖理解組件的概念，但找不到在 Symfony/Api 平台中使用它們的方法。

我如何在不同的端點重用枚舉？

Answer 1

枚舉對於 PHP 來說是相當新的，它們還沒有被 Api 平台直接支持。

支持將會到來，但目前您必須在配置中手動明確列出每種情況。

---

雖然您也可以將“案例”列表存儲在 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,