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,61 @@ parameters:
 			identifier: class.notFound
 			count: 2
 			path: src/Render/Html/HtmlOpenApiRenderer.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']) {
+                $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',
+                version_compare(Kernel::VERSION, '7.4.0', '>=') ? null : 'symfony-7.3',
+                [],
+                [
+                    'nelmio_api_doc' => [
+                        'type_info' => true,
+                    ],
+                ],
+            ];
+        }
+
         yield 'Custom model names' => [
             'CustomModelNameController',
         ];

tests/Functional/Entity/ArrayShapeTypes.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\Entity;
+
+class ArrayShapeTypes
+{
+    /** @var array{name: string, age: int, email?: string} */
+    public array $sealed;
+
+    /** @var array{id: int, label: string, ...} */
+    public array $unsealed;
+
+    /** @var array{user: array{name: string, age: int}, active: bool} */
+    public array $nested;
+
+    /** @var array{0: string, 1: int} */
+    public array $numericKeys;
+
+    /** @var array{name: ?string, email: ?string} */
+    public array $nullableValues;
+}

tests/Functional/Fixtures/ArrayShapeController.json

@@ -0,0 +1,142 @@
+{
+    "openapi": "3.0.0",
+    "info": {
+        "title": "",
+        "version": "0.0.0"
+    },
+    "paths": {
+        "/array-shapes": {
+            "get": {
+                "operationId": "get_nelmio_apidoc_tests_functional_arrayshape_arrayshapes",
+                "responses": {
+                    "200": {
+                        "description": "Success",
+                        "content": {
+                            "application/json": {
+                                "schema": {
+                                    "$ref": "#/components/schemas/ArrayShapeTypes"
+                                }
+                            }
+                        }
+                    }
+                }
+            }
+        }
+    },
+    "components": {
+        "schemas": {
+            "ArrayShapeTypes": {
+                "required": [
+                    "sealed",
+                    "unsealed",
+                    "nested",
+                    "numericKeys",
+                    "nullableValues"
+                ],
+                "properties": {
+                    "sealed": {
+                        "required": [
+                            "age",
+                            "name"
+                        ],
+                        "properties": {
+                            "age": {
+                                "type": "integer"
+                            },
+                            "email": {
+                                "type": "string"
+                            },
+                            "name": {
+                                "type": "string"
+                            }
+                        },
+                        "type": "object",
+                        "additionalProperties": false
+                    },
+                    "unsealed": {
+                        "required": [
+                            "id",
+                            "label"
+                        ],
+                        "properties": {
+                            "id": {
+                                "type": "integer"
+                            },
+                            "label": {
+                                "type": "string"
+                            }
+                        },
+                        "type": "object",
+                        "additionalProperties": {
+                            "nullable": true
+                        }
+                    },
+                    "nested": {
+                        "required": [
+                            "active",
+                            "user"
+                        ],
+                        "properties": {
+                            "active": {
+                                "type": "boolean"
+                            },
+                            "user": {
+                                "required": [
+                                    "age",
+                                    "name"
+                                ],
+                                "properties": {
+                                    "age": {
+                                        "type": "integer"
+                                    },
+                                    "name": {
+                                        "type": "string"
+                                    }
+                                },
+                                "type": "object",
+                                "additionalProperties": false
+                            }
+                        },
+                        "type": "object",
+                        "additionalProperties": false
+                    },
+                    "numericKeys": {
+                        "required": [
+                            "0",
+                            "1"
+                        ],
+                        "properties": {
+                            "0": {
+                                "type": "string"
+                            },
+                            "1": {
+                                "type": "integer"
+                            }
+                        },
+                        "type": "object",
+                        "additionalProperties": false
+                    },
+                    "nullableValues": {
+                        "required": [
+                            "email",
+                            "name"
+                        ],
+                        "properties": {
+                            "email": {
+                                "type": "string",
+                                "nullable": true
+                            },
+                            "name": {
+                                "type": "string",
+                                "nullable": true
+                            }
+                        },
+                        "type": "object",
+                        "additionalProperties": false
+                    }
+                },
+                "type": "object"
+            }
+        }
+    }
+}