Add polymorphism support (based on discriminator)

[ostrolucky]

Description
This was already closed in #2931, but I would like you to reconsider.

Since it's quite limiting not being able to use Doctrine's Inheritance mapping and OpenAPI has nowadays quite good polymorphism support thanks to discriminator, oneOf, anyOf etc, I believe it makes sense to reconsider support of this. At beginning, I think most people would be fine if APIP at least allowed serialization/deserialization of properties in subclasses. Schema generator could be adjusted later to generate things like this

Main issue I would like to solve is that serializer does not see properties from subclasses. After further debugging I found that PropertyNameCollectionFactory and PropertyMetadataFactory are responsible. However, these factories only accept $resourceClassand not an actual class that Serializer is serializing/deserializing, hence it's not possible to simply add own implementation of these factories.

Example

#[ApiResource()]
#[Doctrine\ORM\Mapping\Entity()]
#[Doctrine\ORM\Mapping\InheritanceType('SINGLE_TABLE')]
#[Doctrine\ORM\Mapping\DiscriminatorColumn('type', 'string')]
#[Doctrine\ORM\Mapping\DiscriminatorMap(self::DISCRIMINATOR_MAPPING)]
#[Symfony\Component\Serializer\Attribute\DiscriminatorMap('type', self::DISCRIMINATOR_MAPPING)]
abstract class DatasyncConnector {
    private const array DISCRIMINATOR_MAPPING = ["SCIM" => SCIMConnector::class, "JSON" => JSONConnector::class];

    public string $type;
}
{}

#[ORM\Entity()]
class SCIMConnector extends DatasyncConnector {
  public ?string $foo = null;
}

#[ORM\Entity()]
class JSONConnector extends DatasyncConnector {
  public ?string $bar = null;
}

Here, I expect serialization will result in

{"type": "SCIM", "foo": "string"}

or

{"type": "JSON", "bar": "string"}

Similarly, deserialization should accept (and write to) these properties

Further context
Currently, I have added support for this in application I'm maintaining by enabling allow_extra_attributes and implementing custom normalizer:

#[AutoconfigureTag('serializer.normalizer', ['priority' => 1])]
class DatasyncConnectorNormalizer implements NormalizerInterface, DenormalizerInterface
{
    public function __construct(
        #[Autowire(service: 'serializer.normalizer.object')]
        private ObjectNormalizer $normalizer,
        #[Autowire(service: 'api_platform.jsonld.normalizer.item')]
        private AbstractNormalizer $jsonldNormalizer,
    ) {}

    public function denormalize(mixed $data, string $type, ?string $format = null, array $context = []): mixed
    {
        return $this->normalizer->denormalize(
            $data,
            $type,
            $format,
            [
                AbstractNormalizer::OBJECT_TO_POPULATE => $this->jsonldNormalizer
                    ->denormalize($data, $type, $format, $context),
            ] + $context,
        );
    }

    public function supportsDenormalization(
        mixed $data,
        string $type,
        ?string $format = null,
        array $context = [],
    ): bool {
        return true;
    }

    public function normalize(
        mixed $data,
        ?string $format = null,
        array $context = [],
    ): null|array|\ArrayObject|bool|float|int|string {
        \assert($data instanceof DatasyncConnector);

        $context['uri_variables'] = ['id' => $data->id];

        return $this->jsonldNormalizer->normalize($data, $format, $context)
            + $this->normalizer->normalize($data, $format, $context);
    }

    public function supportsNormalization(mixed $data, ?string $format = null, array $context = []): bool
    {
        return true;
    }

    public function getSupportedTypes(?string $format): array
    {
        return [DatasyncConnector::class => true];
    }
}

Even OpenAPI schema is adjusted thanks to implementing own OpenApiFactory which generates definitions for subclasses, then linking to them from resource like so

new GetCollection(openapi: new OpenApiOperation(responses: [
    200 => new Response(content: new \ArrayObject(['application/ld+json' => [
        'schema' => [
            'type' => 'array',
            'items' => [
                'oneOf' => [
                    ['$ref' => self::SCHEMA_PATH_PREFIX.'.jsonld-connector.output'],
                    ['$ref' => self::SCHEMA_PATH_PREFIX.'.jsonld-connector.output_MS_GRAPH'],
                ],
                'discriminator' => [
                    'propertyName' => 'type',
                    'mapping' => [
                        DatasyncConnectorType::SCIM->value
                        => self::SCHEMA_PATH_PREFIX.'.jsonld-connector.output',
                        DatasyncConnectorType::JSON->value
                        => self::SCHEMA_PATH_PREFIX.'.jsonld-connector.output',
                        DatasyncConnectorType::MS_GRAPH->value
                        => self::SCHEMA_PATH_PREFIX.'.jsonld-connector.output_MS_GRAPH',
                    ],
                ],
            ],
        ],
    ]])),
])),

[soyuka]

See also https://gist.github.com/vincentchalamon/456fb84af4ddf1281a63a0a06e633c60

+1 to reconsider, PR very welcome.

[c1tru55]

made similar feature, but for Symfony\Component\Serializer\Attribute\DiscriminatorMap. currently works only for inputs, but I suppose easily can be changed and for outputs also.

<?php

namespace App\JsonSchema;

use ApiPlatform\JsonSchema\ResourceMetadataTrait;
use ApiPlatform\JsonSchema\Schema;
use ApiPlatform\JsonSchema\SchemaFactoryInterface;
use ApiPlatform\Metadata\Operation;
use Symfony\Component\DependencyInjection\Attribute\AsDecorator;
use Symfony\Component\DependencyInjection\Attribute\AutowireDecorated;
use Symfony\Component\Serializer\Mapping\Factory\ClassMetadataFactoryInterface;

#[AsDecorator(decorates: 'api_platform.json_schema.schema_factory')]
class DiscriminatorAwareSchemaFactory implements SchemaFactoryInterface
{
    use ResourceMetadataTrait;

    public function __construct(
        #[AutowireDecorated]
        private readonly SchemaFactoryInterface $decorated,
        private readonly ClassMetadataFactoryInterface $serializerClassMetadataFactory,
    ) {
    }

    public function buildSchema(string $className, string $format = 'json', string $type = Schema::TYPE_OUTPUT, ?Operation $operation = null, ?Schema $schema = null, ?array $serializerContext = null, bool $forceCollection = false): Schema
    {
        if (
            $type === Schema::TYPE_INPUT
            && $this->isResourceClass($className)
        ) {
            $operation = $this->findOperation($className, $type, $operation, $serializerContext);
            $inputOrOutputClass = $this->findOutputClass($className, $type, $operation, $serializerContext);
            $serializerContext ??= $this->getSerializerContext($operation, $type);

            if (null !== $inputOrOutputClass) {
                $classMetadata = $this->serializerClassMetadataFactory->getMetadataFor($inputOrOutputClass);
                $classDiscriminatorMapping = $classMetadata->getClassDiscriminatorMapping();

                if (null !== $classDiscriminatorMapping) {
                    $definitions = $schema->getDefinitions();

                    $discriminatorSchemas = [];
                    foreach ($classDiscriminatorMapping->getTypesMapping() as $typePropertyValue => $typeClassName) {
                        $discriminatorSchema = $this->decorated->buildSchema($typeClassName, $format, $type, $operation, $schema, $serializerContext, $forceCollection);

                        $discriminatorPropertySchema = $definitions[$discriminatorSchema->getRootDefinitionKey()]['properties'][$classDiscriminatorMapping->getTypeProperty()];

                        unset($discriminatorPropertySchema['enum']);
                        $discriminatorPropertySchema['const'] = $typePropertyValue;

                        if (
                            is_array($discriminatorPropertySchema['type'])
                            && false !== ($nullIndex = array_search('null', $discriminatorPropertySchema['type'], true))
                        ) {
                            unset($discriminatorPropertySchema['type'][$nullIndex]);

                            if (1 === count($discriminatorPropertySchema['type'])) {
                                $discriminatorPropertySchema['type'] = reset($discriminatorPropertySchema['type']);
                            }
                        }

                        $discriminatorSchemas[$typePropertyValue] = $discriminatorSchema;
                    }

                    $originalSchema = $this->decorated->buildSchema($className, $format, $type, $operation, $schema, $serializerContext, $forceCollection);

                    $newDefinition = new \ArrayObject([
                        'oneOf' => array_values(array_map(static fn (Schema $discriminatorSchema) => ['$ref' => $discriminatorSchema['$ref']], $discriminatorSchemas)),
                        'discriminator' => [
                            'propertyName' => $classDiscriminatorMapping->getTypeProperty(),
                            'mapping' => array_map(static fn (Schema $discriminatorSchema) => $discriminatorSchema['$ref'], $discriminatorSchemas),
                        ],
                        'required' => [
                            $classDiscriminatorMapping->getTypeProperty(),
                        ],
                        'properties' => [
                            $classDiscriminatorMapping->getTypeProperty() => [
                                'type' => 'string',
                                'enum' => array_keys($discriminatorSchemas),
                            ],
                        ],
                    ]);
                    $definitions[$originalSchema->getRootDefinitionKey()] = $newDefinition;

                    return $originalSchema;
                }
            }
        }

        return $this->decorated->buildSchema($className, $format, $type, $operation, $schema, $serializerContext, $forceCollection);
    }
}