Create an enum model describer (#1965)

* Create an enum model describer

* Bump Api-Platform

Co-authored-by: Guilhem Niot <guilhem@gniot.fr>

ModelDescriber/EnumModelDescriber.php

@@ -0,0 +1,34 @@
+<?php
+
+namespace Nelmio\ApiDocBundle\ModelDescriber;
+
+use Nelmio\ApiDocBundle\Model\Model;
+use OpenApi\Annotations\Schema;
+use Symfony\Component\PropertyInfo\Type;
+
+class EnumModelDescriber implements ModelDescriberInterface
+{
+    public function describe(Model $model, Schema $schema)
+    {
+        $enumClass = $model->getType()->getClassName();
+
+        $enums = [];
+        foreach ($enumClass::cases() as $enumCase) {
+            $enums[] = $enumCase->value;
+        }
+
+        $schema->type = is_subclass_of($enumClass, \IntBackedEnum::class) ? 'int' : 'string';
+        $schema->enum = $enums;
+    }
+
+    public function supports(Model $model): bool
+    {
+        if (!function_exists('enum_exists')) {
+            return false;
+        }
+
+        return Type::BUILTIN_TYPE_OBJECT === $model->getType()->getBuiltinType()
+            && enum_exists($model->getType()->getClassName())
+            && is_subclass_of($model->getType()->getClassName(), \BackedEnum::class);
+    }
+}

Resources/config/services.xml

@@ -79,6 +79,10 @@
             <tag name="nelmio_api_doc.model_describer" />
         </service>
 
+        <service id="nelmio_api_doc.model_describers.enum" class="Nelmio\ApiDocBundle\ModelDescriber\EnumModelDescriber" public="false">
+            <tag name="nelmio_api_doc.model_describer" priority="100"/>
+        </service>
+
         <service id="nelmio_api_doc.model_describers.object_fallback" class="Nelmio\ApiDocBundle\ModelDescriber\FallbackObjectModelDescriber" public="false">
             <tag name="nelmio_api_doc.model_describer" priority="-1000" />
         </service>

Tests/Functional/Controller/ApiController81.php

@@ -15,6 +15,7 @@
 use Nelmio\ApiDocBundle\Annotation\Model;
 use Nelmio\ApiDocBundle\Annotation\Security;
 use Nelmio\ApiDocBundle\Tests\Functional\Entity\Article;
+use Nelmio\ApiDocBundle\Tests\Functional\Entity\Article81;
 use OpenApi\Attributes as OA;
 use Symfony\Component\Routing\Annotation\Route;
 
@@ -65,4 +66,10 @@ public function inlinePathParameters(
         #[OA\PathParameter] string $product_id
     ) {
     }
+
+    #[Route('/enum')]
+    #[OA\Response(response: '201', description: '', attachables: [new Model(type: Article81::class)])]
+    public function enum()
+    {
+    }
 }

Tests/Functional/Entity/Article81.php

@@ -0,0 +1,12 @@
+<?php
+
+namespace Nelmio\ApiDocBundle\Tests\Functional\Entity;
+
+class Article81
+{
+    public function __construct(
+        public readonly int $id,
+        public readonly ArticleType81 $type,
+    ) {
+    }
+}

Tests/Functional/Entity/ArticleType81.php

@@ -0,0 +1,9 @@
+<?php
+
+namespace Nelmio\ApiDocBundle\Tests\Functional\Entity;
+
+enum ArticleType81: string
+{
+    case DRAFT = 'draft';
+    case FINAL = 'final';
+}

Tests/Functional/FunctionalTest.php

@@ -624,4 +624,15 @@ public function testNoAdditionalPropertiesSupport()
 
         $this->assertFalse($model->additionalProperties);
     }
+
+    /**
+     * @requires PHP >= 8.1
+     */
+    public function testEnumSupport()
+    {
+        $model = $this->getModel('ArticleType81');
+
+        $this->assertSame('string', $model->type);
+        $this->assertCount(2, $model->enum);
+    }
 }

composer.json

@@ -48,7 +48,7 @@
         "symfony/twig-bundle": "^4.4|^5.2|^6.0",
         "symfony/validator": "^4.4|^5.2|^6.0",
 
-        "api-platform/core": "^2.4",
+        "api-platform/core": "^2.6.8",
         "friendsofsymfony/rest-bundle": "^2.8|^3.0",
         "willdurand/hateoas-bundle": "^1.0|^2.0",
         "jms/serializer-bundle": "^2.3|^3.0|^4.0",