feat: add ArrayShapeDescriber for precise array shape documentation

config/services.php

@@ -258,4 +258,12 @@
            ->private()
            ->tag('nelmio_api_doc.type_describer', ['priority' => -1000])
     ;
+
+    if (class_exists(\Symfony\Component\TypeInfo\Type\ArrayShapeType::class)) {
+        $container->services()
+           ->set('nelmio_api_doc.type_describer.array_shape', \Nelmio\ApiDocBundle\TypeDescriber\ArrayShapeDescriber::class)
+               ->private()
+               ->tag('nelmio_api_doc.type_describer', ['priority' => -990])
+        ;
+    }
 };

phpstan-baseline.neon

@@ -41,3 +41,67 @@ parameters:
 			identifier: class.notFound
 			count: 2
 			path: src/Render/Html/HtmlOpenApiRenderer.php
+
+		-
+			message: '#^Unable to resolve the template type T in call to static method Symfony\\Component\\TypeInfo\\Type\:\:collection\(\)$#'
+			identifier: argument.templateType
+			count: 1
+			path: src/Util/LegacyTypeConverter.php
+
+		-
+			message: '#^PHPDoc tag @implements has invalid type Symfony\\Component\\TypeInfo\\Type\\ArrayShapeType\.$#'
+			count: 1
+			path: src/TypeDescriber/ArrayShapeDescriber.php
+
+		-
+			message: '#^Type Symfony\\Component\\TypeInfo\\Type\\ArrayShapeType in generic type Nelmio\\ApiDocBundle\\TypeDescriber\\TypeDescriberInterface\<Symfony\\Component\\TypeInfo\\Type\\ArrayShapeType\> in PHPDoc tag @implements is not subtype of template type T of Symfony\\Component\\TypeInfo\\Type of interface Nelmio\\ApiDocBundle\\TypeDescriber\\TypeDescriberInterface\.$#'
+			count: 1
+			path: src/TypeDescriber/ArrayShapeDescriber.php
+
+		-
+			message: '#^Parameter \$type of method Nelmio\\ApiDocBundle\\TypeDescriber\\ArrayShapeDescriber\:\:describe\(\) has invalid type Symfony\\Component\\TypeInfo\\Type\\ArrayShapeType\.$#'
+			identifier: class.notFound
+			count: 1
+			path: src/TypeDescriber/ArrayShapeDescriber.php
+
+		-
+			message: '#^Call to an undefined method Symfony\\Component\\TypeInfo\\Type\:\:getShape\(\)\.$#'
+			identifier: method.notFound
+			count: 1
+			path: src/TypeDescriber/ArrayShapeDescriber.php
+
+		-
+			message: '#^Call to an undefined method Symfony\\Component\\TypeInfo\\Type\:\:isSealed\(\)\.$#'
+			identifier: method.notFound
+			count: 1
+			path: src/TypeDescriber/ArrayShapeDescriber.php
+
+		-
+			message: '#^Call to an undefined method Symfony\\Component\\TypeInfo\\Type\:\:getExtraValueType\(\)\.$#'
+			identifier: method.notFound
+			count: 1
+			path: src/TypeDescriber/ArrayShapeDescriber.php
+
+		-
+			message: '#^Parameter \$type of method Nelmio\\ApiDocBundle\\TypeDescriber\\ArrayShapeDescriber\:\:supports\(\) has invalid type Symfony\\Component\\TypeInfo\\Type\\ArrayShapeType\.$#'
+			identifier: class.notFound
+			count: 1
+			path: src/TypeDescriber/ArrayShapeDescriber.php
+
+		-
+			message: '#^Class Symfony\\Component\\TypeInfo\\Type\\ArrayShapeType not found\.$#'
+			identifier: class.notFound
+			count: 1
+			path: src/TypeDescriber/ArrayShapeDescriber.php
+
+		-
+			message: '#^Class Symfony\\Component\\TypeInfo\\Type\\ArrayShapeType not found\.$#'
+			identifier: class.notFound
+			count: 1
+			path: src/TypeDescriber/DictionaryDescriber.php
+
+		-
+			message: '#^Class Symfony\\Component\\TypeInfo\\Type\\ArrayShapeType not found\.$#'
+			identifier: class.notFound
+			count: 1
+			path: src/TypeDescriber/ListDescriber.php

src/TypeDescriber/ArrayShapeDescriber.php

@@ -0,0 +1,59 @@
+<?php
+
+/*
+ * This file is part of the NelmioApiDocBundle package.
+ *
+ * (c) Nelmio
+ *
+ * For the full copyright and license information, please view the LICENSE
+ * file that was distributed with this source code.
+ */
+
+namespace Nelmio\ApiDocBundle\TypeDescriber;
+
+use Nelmio\ApiDocBundle\OpenApiPhp\Util;
+use OpenApi\Annotations as OA;
+use OpenApi\Annotations\Schema;
+use Symfony\Component\TypeInfo\Type;
+use Symfony\Component\TypeInfo\Type\ArrayShapeType;
+
+/**
+ * @implements TypeDescriberInterface<ArrayShapeType>
+ *
+ * @internal
+ */
+final class ArrayShapeDescriber implements TypeDescriberInterface, TypeDescriberAwareInterface
+{
+    use TypeDescriberAwareTrait;
+
+    public function describe(Type $type, Schema $schema, array $context = []): void
+    {
+        $schema->type = 'object';
+        $required = [];
+
+        foreach ($type->getShape() as $key => $shapeValue) {
+            $property = Util::getProperty($schema, (string) $key);
+            $this->describer->describe($shapeValue['type'], $property, $context);
+
+            if (!($shapeValue['optional'] ?? false)) {
+                $required[] = (string) $key;
+            }
+        }
+
+        if ([] !== $required) {
+            $schema->required = $required;
+        }
+
+        if (!$type->isSealed()) {
+            $additionalProperties = Util::getChild($schema, OA\AdditionalProperties::class);
+            $this->describer->describe($type->getExtraValueType(), $additionalProperties, $context);
+        } else {
+            $schema->additionalProperties = false;
+        }
+    }
+
+    public function supports(Type $type, array $context = []): bool
+    {
+        return $type instanceof ArrayShapeType;
+    }
+}

src/TypeDescriber/DictionaryDescriber.php

@@ -38,6 +38,7 @@ public function describe(Type $type, Schema $schema, array $context = []): void
     public function supports(Type $type, array $context = []): bool
     {
         return $type instanceof CollectionType
+            && !$type instanceof Type\ArrayShapeType
             && $type->getCollectionKeyType() instanceof Type\BuiltinType
             && TypeIdentifier::STRING === $type->getCollectionKeyType()->getTypeIdentifier();
     }

src/TypeDescriber/ListDescriber.php

@@ -38,6 +38,7 @@ public function describe(Type $type, Schema $schema, array $context = []): void
     public function supports(Type $type, array $context = []): bool
     {
         return $type instanceof CollectionType
+            && !$type instanceof Type\ArrayShapeType
             && $type->getCollectionKeyType() instanceof Type\BuiltinType
             && TypeIdentifier::INT === $type->getCollectionKeyType()->getTypeIdentifier();
     }

tests/Functional/Controller/ArrayShapeController.php

@@ -0,0 +1,32 @@
+<?php
+
+declare(strict_types=1);
+
+/*
+ * This file is part of the NelmioApiDocBundle package.
+ *
+ * (c) Nelmio
+ *
+ * For the full copyright and license information, please view the LICENSE
+ * file that was distributed with this source code.
+ */
+
+namespace Nelmio\ApiDocBundle\Tests\Functional\Controller;
+
+use Nelmio\ApiDocBundle\Attribute\Model;
+use Nelmio\ApiDocBundle\Tests\Functional\Entity\ArrayShapeTypes;
+use OpenApi\Attributes as OA;
+use Symfony\Component\Routing\Attribute\Route;
+
+class ArrayShapeController
+{
+    #[OA\Response(
+        response: '200',
+        description: 'Success',
+        content: new Model(type: ArrayShapeTypes::class),
+    )]
+    #[Route('/array-shapes', methods: ['GET'])]
+    public function arrayShapesAction(): void
+    {
+    }
+}

tests/Functional/ControllerTest.php

@@ -717,6 +717,19 @@ static function (RoutingConfigurator $routes) {
             ];
         }
 
+        if (version_compare(Kernel::VERSION, '7.3.0', '>=') && class_exists(TypeInfoType\ArrayShapeType::class)) {
+            yield 'Array shape types' => [
+                'ArrayShapeController',
+                null,
+                [],
+                [
+                    'nelmio_api_doc' => [
+                        'type_info' => true,
+                    ],
+                ],
+            ];
+        }
+
         yield 'Custom model names' => [
             'CustomModelNameController',
         ];

tests/Functional/Entity/ArrayShapeTypes.php

@@ -0,0 +1,23 @@
+<?php
+
+declare(strict_types=1);
+
+/*
+ * This file is part of the NelmioApiDocBundle package.
+ *
+ * (c) Nelmio
+ *
+ * For the full copyright and license information, please view the LICENSE
+ * file that was distributed with this source code.
+ */
+
+namespace Nelmio\ApiDocBundle\Tests\Functional\Entity;
+
+class ArrayShapeTypes
+{
+    /** @var array{name: string, age: int, email?: string} */
+    public array $sealed;
+
+    /** @var array{id: int, label: string, ...} */
+    public array $unsealed;
+}