feat(#2212): support experimental type info component

.github/workflows/continuous-integration.yml

@@ -127,7 +127,7 @@ jobs:
       - name: Setup dependencies
         uses: ./.github/workflows/common/composer-install
         with:
-          symfony-version: "7.0.*"
+          symfony-version: "7.1.*"
           install-doctrine-annotations: false
 
       - name: Run PHPStan

config/services.xml

@@ -161,6 +161,61 @@
         <service id="nelmio_api_doc.swagger.processor.nullable_property" class="Nelmio\ApiDocBundle\Processor\NullablePropertyProcessor">
             <tag name="nelmio_api_doc.swagger.processor" />
         </service>
+
+        <!-- Experimental schema describers (symfony/type-info) -->
+        <service id="nelmio_api_doc.schema_describer.chain" class="Nelmio\ApiDocBundle\TypeDescriber\ChainDescriber" public="false">
+            <argument type="tagged" tag="nelmio_api_doc.schema_describer" />
+
+            <tag name="nelmio_api_doc.schema_describer" priority="100" />
+        </service>
+
+        <service id="nelmio_api_doc.schema_describer.bool" class="Nelmio\ApiDocBundle\TypeDescriber\BoolDescriber" public="false">
+            <tag name="nelmio_api_doc.schema_describer" />
+        </service>
+
+        <service id="nelmio_api_doc.schema_describer.dictionary" class="Nelmio\ApiDocBundle\TypeDescriber\DictionaryDescriber" public="false">
+            <tag name="nelmio_api_doc.schema_describer" />
+        </service>
+
+        <service id="nelmio_api_doc.schema_describer.float" class="Nelmio\ApiDocBundle\TypeDescriber\FloatDescriber" public="false">
+            <tag name="nelmio_api_doc.schema_describer" />
+        </service>
+
+        <service id="nelmio_api_doc.schema_describer.integer" class="Nelmio\ApiDocBundle\TypeDescriber\IntegerDescriber" public="false">
+            <tag name="nelmio_api_doc.schema_describer" />
+        </service>
+
+        <service id="nelmio_api_doc.schema_describer.intersection" class="Nelmio\ApiDocBundle\TypeDescriber\IntersectionDescriber" public="false">
+            <tag name="nelmio_api_doc.schema_describer" />
+        </service>
+
+        <service id="nelmio_api_doc.schema_describer.list" class="Nelmio\ApiDocBundle\TypeDescriber\ListDescriber" public="false">
+            <tag name="nelmio_api_doc.schema_describer" />
+        </service>
+
+        <service id="nelmio_api_doc.schema_describer.mixed" class="Nelmio\ApiDocBundle\TypeDescriber\MixedDescriber" public="false">
+            <tag name="nelmio_api_doc.schema_describer" />
+        </service>
+
+        <service id="nelmio_api_doc.schema_describer.nullable" class="Nelmio\ApiDocBundle\TypeDescriber\NullableDescriber" public="false">
+            <tag name="nelmio_api_doc.schema_describer" />
+        </service>
+
+        <service id="nelmio_api_doc.schema_describer.object_class" class="Nelmio\ApiDocBundle\TypeDescriber\ObjectClassDescriber" public="false">
+            <tag name="nelmio_api_doc.schema_describer" />
+        </service>
+
+        <service id="nelmio_api_doc.schema_describer.object" class="Nelmio\ApiDocBundle\TypeDescriber\ObjectDescriber" public="false">
+            <tag name="nelmio_api_doc.schema_describer" />
+        </service>
+
+        <service id="nelmio_api_doc.schema_describer.string" class="Nelmio\ApiDocBundle\TypeDescriber\StringDescriber" public="false">
+            <tag name="nelmio_api_doc.schema_describer" />
+        </service>
+
+        <service id="nelmio_api_doc.schema_describer.union" class="Nelmio\ApiDocBundle\TypeDescriber\UnionDescriber" public="false">
+            <tag name="nelmio_api_doc.schema_describer" />
+        </service>
     </services>
 
 </container>

phpstan-baseline.neon

@@ -5,6 +5,11 @@ parameters:
 			count: 1
 			path: src/Describer/ExternalDocDescriber.php
 
+		-
+			message: "#^Call to function method_exists\\(\\) with Symfony\\\\Component\\\\PropertyInfo\\\\PropertyInfoExtractorInterface and 'getType' will always evaluate to true\\.$#"
+			count: 1
+			path: src/ModelDescriber/ObjectModelDescriber.php
+
 		-
 			message: "#^Method Nelmio\\\\ApiDocBundle\\\\PropertyDescriber\\\\PropertyDescriberInterface\\:\\:describe\\(\\) invoked with 5 parameters, 2\\-3 required\\.$#"
 			count: 1

src/DependencyInjection/Configuration.php

@@ -25,6 +25,10 @@ public function getConfigTreeBuilder(): TreeBuilder
 
         $rootNode
             ->children()
+                ->booleanNode('experimental_type_info')
+                    ->info('Use the symfony/type-info component for determining types. This is experimental and could be changed at any time without prior notice.')
+                    ->defaultFalse()
+                ->end()
                 ->booleanNode('use_validation_groups')
                     ->info('If true, `groups` passed to @Model annotations will be used to limit validation constraints')
                     ->defaultFalse()

src/DependencyInjection/NelmioApiDocExtension.php

@@ -164,6 +164,11 @@ public function load(array $configs, ContainerBuilder $container): void
                 array_map(function ($area) { return new Reference(sprintf('nelmio_api_doc.generator.%s', $area)); }, array_keys($config['areas']))
             ));
 
+        if (true === $config['experimental_type_info']) {
+            $container->getDefinition('nelmio_api_doc.model_describers.object')
+                ->setArgument(2, new Reference('nelmio_api_doc.schema_describer.chain'));
+        }
+
         $container->getDefinition('nelmio_api_doc.model_describers.object')
             ->setArgument(3, $config['media_types']);
 

src/ModelDescriber/ObjectModelDescriber.php

@@ -18,6 +18,7 @@
 use Nelmio\ApiDocBundle\ModelDescriber\Annotations\AnnotationsReader;
 use Nelmio\ApiDocBundle\OpenApiPhp\Util;
 use Nelmio\ApiDocBundle\PropertyDescriber\PropertyDescriberInterface;
+use Nelmio\ApiDocBundle\TypeDescriber\TypeDescriberInterface;
 use OpenApi\Annotations as OA;
 use OpenApi\Generator;
 use Symfony\Component\PropertyInfo\PropertyInfoExtractorInterface;
@@ -34,7 +35,7 @@ class ObjectModelDescriber implements ModelDescriberInterface, ModelRegistryAwar
     private PropertyInfoExtractorInterface $propertyInfo;
     private ?ClassMetadataFactoryInterface $classMetadataFactory;
     private ?Reader $doctrineReader;
-    /** @var PropertyDescriberInterface|PropertyDescriberInterface[] */
+    /** @var PropertyDescriberInterface|PropertyDescriberInterface[]|TypeDescriberInterface */
     private $propertyDescriber;
     /** @var string[] */
     private array $mediaTypes;
@@ -43,9 +44,9 @@ class ObjectModelDescriber implements ModelDescriberInterface, ModelRegistryAwar
     private bool $useValidationGroups;
 
     /**
-     * @param PropertyDescriberInterface|PropertyDescriberInterface[]      $propertyDescribers
-     * @param (NameConverterInterface&AdvancedNameConverterInterface)|null $nameConverter
-     * @param string[]                                                     $mediaTypes
+     * @param PropertyDescriberInterface|PropertyDescriberInterface[]|TypeDescriberInterface $propertyDescribers
+     * @param (NameConverterInterface&AdvancedNameConverterInterface)|null                   $nameConverter
+     * @param string[]                                                                       $mediaTypes
      */
     public function __construct(
         PropertyInfoExtractorInterface $propertyInfo,
@@ -59,7 +60,7 @@ public function __construct(
         if (is_iterable($propertyDescribers)) {
             trigger_deprecation('nelmio/api-doc-bundle', '4.17', 'Passing an array of PropertyDescriberInterface to %s() is deprecated. Pass a single PropertyDescriberInterface instead.', __METHOD__);
         } else {
-            if (!$propertyDescribers instanceof PropertyDescriberInterface) {
+            if (!$propertyDescribers instanceof PropertyDescriberInterface && !$propertyDescribers instanceof TypeDescriberInterface) {
                 throw new \InvalidArgumentException(sprintf('Argument 3 passed to %s() must be an array of %s or a single %s.', __METHOD__, PropertyDescriberInterface::class, PropertyDescriberInterface::class));
             }
         }
@@ -175,12 +176,36 @@ public function describe(Model $model, OA\Schema $schema)
                 continue;
             }
 
-            $types = $this->propertyInfo->getTypes($class, $propertyName);
-            if (null === $types || 0 === count($types)) {
-                throw new \LogicException(sprintf('The PropertyInfo component was not able to guess the type of %s::$%s. You may need to add a `@var` annotation or use `@OA\Property(type="")` to make its type explicit.', $class, $propertyName));
+            /*
+             * @experimental
+             */
+            if ($this->propertyDescriber instanceof TypeDescriberInterface) {
+                if (false === method_exists($this->propertyInfo, 'getType')) {
+                    throw new \RuntimeException('The PropertyInfo component is missing the "getType" method. Are you running on version 7.1?');
+                }
+
+                $type = $this->propertyInfo->getType($class, $propertyName);
+                if (null === $type) {
+                    throw new \LogicException(sprintf('The PropertyInfo component was not able to guess the type of %s::$%s. You may need to add a `@var` annotation or use `@OA\Property(type="")` to make its type explicit.', $class, $propertyName));
+                }
+
+                if ($this->propertyDescriber instanceof ModelRegistryAwareInterface) {
+                    $this->propertyDescriber->setModelRegistry($this->modelRegistry);
+                }
+
+                if (!$this->propertyDescriber->supports($type, $model->getSerializationContext())) {
+                    throw new \Exception(sprintf('Type "%s" $model->getSerializationContext() not supported in %s::$%s. You may use the `@OA\Property(type="")` annotation to specify it manually.', $type->__toString(), $model->getType()->getClassName(), $propertyName));
+                }
+
+                $this->propertyDescriber->describe($type, $property, $model->getSerializationContext());
+            } else {
+                $types = $this->propertyInfo->getTypes($class, $propertyName);
+                if (null === $types || 0 === count($types)) {
+                    throw new \LogicException(sprintf('The PropertyInfo component was not able to guess the type of %s::$%s. You may need to add a `@var` annotation or use `@OA\Property(type="")` to make its type explicit.', $class, $propertyName));
+                }
+
+                $this->describeProperty($types, $model, $property, $propertyName, $schema);
             }
-
-            $this->describeProperty($types, $model, $property, $propertyName, $schema);
         }
 
         $this->markRequiredProperties($schema);

src/PropertyDescriber/RequiredPropertyDescriber.php

@@ -11,6 +11,7 @@
 
 namespace Nelmio\ApiDocBundle\PropertyDescriber;
 
+use Nelmio\ApiDocBundle\ModelDescriber\ObjectModelDescriber;
 use OpenApi\Annotations as OA;
 use OpenApi\Generator;
 

src/TypeDescriber/BoolDescriber.php

@@ -0,0 +1,37 @@
+<?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 OpenApi\Annotations\Schema;
+use Symfony\Component\TypeInfo\Type;
+use Symfony\Component\TypeInfo\TypeIdentifier;
+
+/**
+ * @implements TypeDescriberInterface<Type\BuiltinType>
+ *
+ * @experimental
+ *
+ * @internal
+ */
+final class BoolDescriber implements TypeDescriberInterface
+{
+    public function describe(Type $type, Schema $schema, array $context = []): void
+    {
+        $schema->type = 'boolean';
+    }
+
+    public function supports(Type $type, array $context = []): bool
+    {
+        return $type instanceof Type\BuiltinType
+            && $type->isA(TypeIdentifier::BOOL);
+    }
+}

src/TypeDescriber/ChainDescriber.php

@@ -0,0 +1,68 @@
+<?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\Describer\ModelRegistryAwareInterface;
+use Nelmio\ApiDocBundle\Describer\ModelRegistryAwareTrait;
+use OpenApi\Annotations\Schema;
+use Symfony\Component\TypeInfo\Type;
+
+/**
+ * @implements TypeDescriberInterface<Type>
+ *
+ * @experimental
+ *
+ * @internal
+ */
+final class ChainDescriber implements TypeDescriberInterface, ModelRegistryAwareInterface
+{
+    use ModelRegistryAwareTrait;
+
+    /** @var iterable<TypeDescriberInterface> */
+    private iterable $describers;
+
+    /**
+     * @param iterable<TypeDescriberInterface> $describers
+     */
+    public function __construct(
+        iterable $describers
+    ) {
+        $this->describers = $describers;
+    }
+
+    public function describe(Type $type, Schema $schema, array $context = []): void
+    {
+        foreach ($this->describers as $describer) {
+            /* BC layer for Symfony < 6.3 @see https://symfony.com/doc/6.3/service_container/tags.html#reference-tagged-services */
+            if ($describer instanceof self) {
+                continue;
+            }
+
+            if ($describer instanceof ModelRegistryAwareInterface) {
+                $describer->setModelRegistry($this->modelRegistry);
+            }
+
+            if ($describer instanceof TypeDescriberAwareInterface) {
+                $describer->setDescriber($this);
+            }
+
+            if ($describer->supports($type, $context)) {
+                $describer->describe($type, $schema, $context);
+            }
+        }
+    }
+
+    public function supports(Type $type, array $context = []): bool
+    {
+        return true;
+    }
+}

src/TypeDescriber/DictionaryDescriber.php

@@ -0,0 +1,45 @@
+<?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\CollectionType;
+use Symfony\Component\TypeInfo\TypeIdentifier;
+
+/**
+ * @implements TypeDescriberInterface<CollectionType>
+ *
+ * @experimental
+ *
+ * @internal
+ */
+final class DictionaryDescriber implements TypeDescriberInterface, TypeDescriberAwareInterface
+{
+    use TypeDescriberAwareTrait;
+
+    public function describe(Type $type, Schema $schema, array $context = []): void
+    {
+        $schema->type = 'object';
+        $additionalProperties = Util::getChild($schema, OA\AdditionalProperties::class);
+
+        $this->describer->describe($type->getCollectionValueType(), $additionalProperties, $context);
+    }
+
+    public function supports(Type $type, array $context = []): bool
+    {
+        return $type instanceof CollectionType
+            && $type->getCollectionKeyType()->isA(TypeIdentifier::STRING);
+    }
+}

src/TypeDescriber/FloatDescriber.php

@@ -0,0 +1,38 @@
+<?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 OpenApi\Annotations\Schema;
+use Symfony\Component\TypeInfo\Type;
+use Symfony\Component\TypeInfo\TypeIdentifier;
+
+/**
+ * @implements TypeDescriberInterface<Type\BuiltinType>
+ *
+ * @experimental
+ *
+ * @internal
+ */
+final class FloatDescriber implements TypeDescriberInterface
+{
+    public function describe(Type $type, Schema $schema, array $context = []): void
+    {
+        $schema->type = 'number';
+        $schema->format = 'float';
+    }
+
+    public function supports(Type $type, array $context = []): bool
+    {
+        return $type instanceof Type\BuiltinType
+            && $type->isA(TypeIdentifier::FLOAT);
+    }
+}