vendor/api-platform/core/src/Hydra/Serializer/DocumentationNormalizer.php line 77

Open in your IDE?
  1. <?php
  3. /*
  4.  * This file is part of the API Platform project.
  5.  *
  6.  * (c) Kévin Dunglas <dunglas@gmail.com>
  7.  *
  8.  * For the full copyright and license information, please view the LICENSE
  9.  * file that was distributed with this source code.
  10.  */
  12. declare(strict_types=1);
  14. namespace ApiPlatform\Hydra\Serializer;
  16. use ApiPlatform\Api\ResourceClassResolverInterface;
  17. use ApiPlatform\Api\UrlGeneratorInterface;
  18. use ApiPlatform\Core\Api\OperationMethodResolverInterface;
  19. use ApiPlatform\Core\Api\OperationType;
  20. use ApiPlatform\Core\Metadata\Property\Factory\PropertyMetadataFactoryInterface as LegacyPropertyMetadataFactoryInterface;
  21. use ApiPlatform\Core\Metadata\Property\Factory\PropertyNameCollectionFactoryInterface;
  22. use ApiPlatform\Core\Metadata\Property\PropertyMetadata;
  23. use ApiPlatform\Core\Metadata\Property\SubresourceMetadata;
  24. use ApiPlatform\Core\Metadata\Resource\Factory\ResourceMetadataFactoryInterface;
  25. use ApiPlatform\Core\Metadata\Resource\ResourceMetadata;
  26. use ApiPlatform\Core\Operation\Factory\SubresourceOperationFactoryInterface;
  27. use ApiPlatform\Documentation\Documentation;
  28. use ApiPlatform\JsonLd\ContextBuilderInterface;
  29. use ApiPlatform\Metadata\ApiProperty;
  30. use ApiPlatform\Metadata\ApiResource;
  31. use ApiPlatform\Metadata\CollectionOperationInterface;
  32. use ApiPlatform\Metadata\HttpOperation;
  33. use ApiPlatform\Metadata\Operation;
  34. use ApiPlatform\Metadata\Property\Factory\PropertyMetadataFactoryInterface;
  35. use ApiPlatform\Metadata\Resource\Factory\ResourceMetadataCollectionFactoryInterface;
  36. use ApiPlatform\Metadata\Resource\ResourceMetadataCollection;
  37. use Symfony\Component\PropertyInfo\Type;
  38. use Symfony\Component\Serializer\NameConverter\NameConverterInterface;
  39. use Symfony\Component\Serializer\Normalizer\AbstractNormalizer;
  40. use Symfony\Component\Serializer\Normalizer\CacheableSupportsMethodInterface;
  41. use Symfony\Component\Serializer\Normalizer\NormalizerInterface;
  43. /**
  44.  * Creates a machine readable Hydra API documentation.
  45.  *
  46.  * @author Kévin Dunglas <dunglas@gmail.com>
  47.  */
  48. final class DocumentationNormalizer implements NormalizerInterface, CacheableSupportsMethodInterface
  49. {
  50.     public const FORMAT = 'jsonld';
  52.     /**
  53.      * @var ResourceMetadataFactoryInterface|ResourceMetadataCollectionFactoryInterface
  54.      */
  55.     private $resourceMetadataFactory;
  56.     private $propertyNameCollectionFactory;
  58.     /**
  59.      * @var PropertyMetadataFactoryInterface|LegacyPropertyMetadataFactoryInterface
  60.      */
  61.     private $propertyMetadataFactory;
  62.     private $resourceClassResolver;
  63.     private $operationMethodResolver;
  64.     private $urlGenerator;
  65.     private $subresourceOperationFactory;
  66.     private $nameConverter;
  68.     public function __construct($resourceMetadataFactory, PropertyNameCollectionFactoryInterface $propertyNameCollectionFactory, $propertyMetadataFactory, ResourceClassResolverInterface $resourceClassResolver, OperationMethodResolverInterface $operationMethodResolver = null, UrlGeneratorInterface $urlGenerator, SubresourceOperationFactoryInterface $subresourceOperationFactory = null, NameConverterInterface $nameConverter = null)
  69.     {
  70.         if ($operationMethodResolver) {
  71.             @trigger_error(sprintf('Passing an instance of %s to %s() is deprecated since version 2.5 and will be removed in 3.0.', OperationMethodResolverInterface::class, __METHOD__), \E_USER_DEPRECATED);
  72.         }
  74.         $this->resourceMetadataFactory = $resourceMetadataFactory;
  76.         if (!$resourceMetadataFactory instanceof ResourceMetadataCollectionFactoryInterface) {
  77.             trigger_deprecation('api-platform/core', '2.7', sprintf('Use "%s" instead of "%s".', ResourceMetadataCollectionFactoryInterface::class, ResourceMetadataFactoryInterface::class));
  78.         }
  80.         if ($subresourceOperationFactory) {
  81.             trigger_deprecation('api-platform/core', '2.7', sprintf('Using "%s" is deprecated and will be removed.', SubresourceOperationFactoryInterface::class));
  82.         }
  84.         $this->propertyNameCollectionFactory = $propertyNameCollectionFactory;
  85.         $this->propertyMetadataFactory = $propertyMetadataFactory;
  86.         $this->resourceClassResolver = $resourceClassResolver;
  87.         $this->operationMethodResolver = $operationMethodResolver;
  88.         $this->urlGenerator = $urlGenerator;
  89.         $this->subresourceOperationFactory = $subresourceOperationFactory;
  90.         $this->nameConverter = $nameConverter;
  91.     }
  93.     /**
  94.      * {@inheritdoc}
  95.      *
  96.      * @return array|string|int|float|bool|\ArrayObject|null
  97.      */
  98.     public function normalize($object, $format = null, array $context = [])
  99.     {
  100.         $classes = [];
  101.         $entrypointProperties = [];
  103.         foreach ($object->getResourceNameCollection() as $resourceClass) {
  104.             $resourceMetadataCollection = $this->resourceMetadataFactory->create($resourceClass);
  106.             if ($resourceMetadataCollection instanceof ResourceMetadata) {
  107.                 $shortName = $resourceMetadataCollection->getShortName();
  108.                 $prefixedShortName = $resourceMetadataCollection->getIri() ?? "#$shortName";
  110.                 $this->populateEntrypointProperties($resourceClass, $resourceMetadataCollection, $shortName, $prefixedShortName, $entrypointProperties);
  111.                 $classes[] = $this->getClass($resourceClass, $resourceMetadataCollection, $shortName, $prefixedShortName, $context);
  112.                 continue;
  113.             }
  115.             $resourceMetadata = $resourceMetadataCollection[0];
  116.             $shortName = $resourceMetadata->getShortName();
  117.             $prefixedShortName = $resourceMetadata->getTypes()[0] ?? "#$shortName";
  118.             $this->populateEntrypointProperties($resourceClass, $resourceMetadata, $shortName, $prefixedShortName, $entrypointProperties, $resourceMetadataCollection);
  119.             $classes[] = $this->getClass($resourceClass, $resourceMetadata, $shortName, $prefixedShortName, $context, $resourceMetadataCollection);
  120.         }
  122.         return $this->computeDoc($object, $this->getClasses($entrypointProperties, $classes));
  123.     }
  125.     /**
  126.      * Populates entrypoint properties.
  127.      *
  128.      * @param ResourceMetadata|ApiResource $resourceMetadata
  129.      */
  130.     private function populateEntrypointProperties(string $resourceClass, $resourceMetadata, string $shortName, string $prefixedShortName, array &$entrypointProperties, ?ResourceMetadataCollection $resourceMetadataCollection = null)
  131.     {
  132.         $hydraCollectionOperations = $this->getHydraOperations($resourceClass, $resourceMetadata, $prefixedShortName, true, $resourceMetadataCollection);
  133.         if (empty($hydraCollectionOperations)) {
  134.             return;
  135.         }
  137.         $entrypointProperty = [
  138.             '@type' => 'hydra:SupportedProperty',
  139.             'hydra:property' => [
  140.                 '@id' => sprintf('#Entrypoint/%s', lcfirst($shortName)),
  141.                 '@type' => 'hydra:Link',
  142.                 'domain' => '#Entrypoint',
  143.                 'rdfs:label' => "The collection of $shortName resources",
  144.                 'rdfs:range' => [
  145.                     ['@id' => 'hydra:Collection'],
  146.                     [
  147.                         'owl:equivalentClass' => [
  148.                             'owl:onProperty' => ['@id' => 'hydra:member'],
  149.                             'owl:allValuesFrom' => ['@id' => $prefixedShortName],
  150.                         ],
  151.                     ],
  152.                 ],
  153.                 'hydra:supportedOperation' => $hydraCollectionOperations,
  154.             ],
  155.             'hydra:title' => "The collection of $shortName resources",
  156.             'hydra:readable' => true,
  157.             'hydra:writeable' => false,
  158.         ];
  160.         if ($resourceMetadata instanceof ResourceMetadata ? $resourceMetadata->getCollectionOperationAttribute('GET', 'deprecation_reason', null, true) : $resourceMetadata->getDeprecationReason()) {
  161.             $entrypointProperty['owl:deprecated'] = true;
  162.         }
  164.         $entrypointProperties[] = $entrypointProperty;
  165.     }
  167.     /**
  168.      * Gets a Hydra class.
  169.      *
  170.      * @param ResourceMetadata|ApiResource $resourceMetadata
  171.      */
  172.     private function getClass(string $resourceClass, $resourceMetadata, string $shortName, string $prefixedShortName, array $context, ?ResourceMetadataCollection $resourceMetadataCollection = null): array
  173.     {
  174.         if ($resourceMetadata instanceof ApiResource) {
  175.             $description = $resourceMetadata->getDescription();
  176.             $isDeprecated = $resourceMetadata->getDeprecationReason();
  177.         } else {
  178.             $description = $resourceMetadata->getDescription();
  179.             $isDeprecated = $resourceMetadata->getAttribute('deprecation_reason');
  180.         }
  182.         $class = [
  183.             '@id' => $prefixedShortName,
  184.             '@type' => 'hydra:Class',
  185.             'rdfs:label' => $shortName,
  186.             'hydra:title' => $shortName,
  187.             'hydra:supportedProperty' => $this->getHydraProperties($resourceClass, $resourceMetadata, $shortName, $prefixedShortName, $context),
  188.             'hydra:supportedOperation' => $this->getHydraOperations($resourceClass, $resourceMetadata, $prefixedShortName, false, $resourceMetadataCollection),
  189.         ];
  191.         if (null !== $description) {
  192.             $class['hydra:description'] = $description;
  193.         }
  195.         if ($isDeprecated) {
  196.             $class['owl:deprecated'] = true;
  197.         }
  199.         return $class;
  200.     }
  202.     /**
  203.      * Gets the context for the property name factory.
  204.      */
  205.     private function getPropertyNameCollectionFactoryContext(ResourceMetadata $resourceMetadata): array
  206.     {
  207.         $attributes = $resourceMetadata->getAttributes();
  208.         $context = [];
  210.         if (isset($attributes['normalization_context'][AbstractNormalizer::GROUPS])) {
  211.             $context['serializer_groups'] = (array) $attributes['normalization_context'][AbstractNormalizer::GROUPS];
  212.         }
  214.         if (!isset($attributes['denormalization_context'][AbstractNormalizer::GROUPS])) {
  215.             return $context;
  216.         }
  218.         if (isset($context['serializer_groups'])) {
  219.             foreach ((array) $attributes['denormalization_context'][AbstractNormalizer::GROUPS] as $groupName) {
  220.                 $context['serializer_groups'][] = $groupName;
  221.             }
  223.             return $context;
  224.         }
  226.         $context['serializer_groups'] = (array) $attributes['denormalization_context'][AbstractNormalizer::GROUPS];
  228.         return $context;
  229.     }
  231.     /**
  232.      * Creates context for property metatata factories.
  233.      */
  234.     private function getPropertyMetadataFactoryContext(ApiResource $resourceMetadata): array
  235.     {
  236.         $normalizationGroups = $resourceMetadata->getNormalizationContext()[AbstractNormalizer::GROUPS] ?? null;
  237.         $denormalizationGroups = $resourceMetadata->getDenormalizationContext()[AbstractNormalizer::GROUPS] ?? null;
  238.         $propertyContext = [
  239.             'normalization_groups' => $normalizationGroups,
  240.             'denormalization_groups' => $denormalizationGroups,
  241.         ];
  242.         $propertyNameContext = [];
  244.         if ($normalizationGroups) {
  245.             $propertyNameContext['serializer_groups'] = $normalizationGroups;
  246.         }
  248.         if (!$denormalizationGroups) {
  249.             return [$propertyNameContext, $propertyContext];
  250.         }
  252.         if (!isset($propertyNameContext['serializer_groups'])) {
  253.             $propertyNameContext['serializer_groups'] = $denormalizationGroups;
  255.             return [$propertyNameContext, $propertyContext];
  256.         }
  258.         foreach ($denormalizationGroups as $group) {
  259.             $propertyNameContext['serializer_groups'][] = $group;
  260.         }
  262.         return [$propertyNameContext, $propertyContext];
  263.     }
  265.     /**
  266.      * Gets Hydra properties.
  267.      *
  268.      * @param ResourceMetadata|ApiResource $resourceMetadata
  269.      */
  270.     private function getHydraProperties(string $resourceClass, $resourceMetadata, string $shortName, string $prefixedShortName, array $context): array
  271.     {
  272.         $classes = [];
  274.         if ($resourceMetadata instanceof ResourceMetadata) {
  275.             foreach ($resourceMetadata->getCollectionOperations() as $operationName => $operation) {
  276.                 $inputMetadata = $resourceMetadata->getTypedOperationAttribute(OperationType::COLLECTION, $operationName, 'input', ['class' => $resourceClass], true);
  277.                 if (null !== $inputClass = $inputMetadata['class'] ?? null) {
  278.                     $classes[$inputClass] = true;
  279.                 }
  281.                 $outputMetadata = $resourceMetadata->getTypedOperationAttribute(OperationType::COLLECTION, $operationName, 'output', ['class' => $resourceClass], true);
  282.                 if (null !== $outputClass = $outputMetadata['class'] ?? null) {
  283.                     $classes[$outputClass] = true;
  284.                 }
  285.             }
  286.         } else {
  287.             $classes[$resourceClass] = true;
  288.             foreach ($resourceMetadata->getOperations() as $operation) {
  289.                 /** @var Operation $operation */
  290.                 if (!$operation instanceof CollectionOperationInterface) {
  291.                     continue;
  292.                 }
  294.                 $inputMetadata = $operation->getInput();
  295.                 if (null !== $inputClass = $inputMetadata['class'] ?? null) {
  296.                     $classes[$inputClass] = true;
  297.                 }
  299.                 $outputMetadata = $operation->getOutput();
  300.                 if (null !== $outputClass = $outputMetadata['class'] ?? null) {
  301.                     $classes[$outputClass] = true;
  302.                 }
  303.             }
  304.         }
  306.         /** @var string[] $classes */
  307.         $classes = array_keys($classes);
  308.         $properties = [];
  309.         if ($resourceMetadata instanceof ResourceMetadata) {
  310.             $propertyNameContext = $this->getPropertyNameCollectionFactoryContext($resourceMetadata);
  311.             $propertyContext = [];
  312.         } else {
  313.             [$propertyNameContext, $propertyContext] = $this->getPropertyMetadataFactoryContext($resourceMetadata);
  314.         }
  316.         foreach ($classes as $class) {
  317.             foreach ($this->propertyNameCollectionFactory->create($class, $propertyNameContext) as $propertyName) {
  318.                 $propertyMetadata = $this->propertyMetadataFactory->create($class, $propertyName, $propertyContext);
  320.                 if (true === $propertyMetadata->isIdentifier() && false === $propertyMetadata->isWritable()) {
  321.                     continue;
  322.                 }
  324.                 if ($this->nameConverter) {
  325.                     $propertyName = $this->nameConverter->normalize($propertyName, $class, self::FORMAT, $context);
  326.                 }
  328.                 $properties[] = $this->getProperty($propertyMetadata, $propertyName, $prefixedShortName, $shortName);
  329.             }
  330.         }
  332.         return $properties;
  333.     }
  335.     /**
  336.      * Gets Hydra operations.
  337.      *
  338.      * @param ResourceMetadata|ApiResource $resourceMetadata
  339.      */
  340.     private function getHydraOperations(string $resourceClass, $resourceMetadata, string $prefixedShortName, bool $collection, ?ResourceMetadataCollection $resourceMetadataCollection = null): array
  341.     {
  342.         if ($resourceMetadata instanceof ResourceMetadata) {
  343.             if (null === $operations = $collection ? $resourceMetadata->getCollectionOperations() : $resourceMetadata->getItemOperations()) {
  344.                 return [];
  345.             }
  347.             $hydraOperations = [];
  348.             foreach ($operations as $operationName => $operation) {
  349.                 $hydraOperations[] = $this->getHydraOperation($resourceClass, $resourceMetadata, $operationName, $operation, $prefixedShortName, $collection ? OperationType::COLLECTION : OperationType::ITEM);
  350.             }
  351.         } else {
  352.             $hydraOperations = [];
  353.             foreach ($resourceMetadataCollection as $resourceMetadata) {
  354.                 foreach ($resourceMetadata->getOperations() as $operationName => $operation) {
  355.                     if ((HttpOperation::METHOD_POST === $operation->getMethod() || $operation instanceof CollectionOperationInterface) !== $collection) {
  356.                         continue;
  357.                     }
  359.                     $hydraOperations[] = $this->getHydraOperation($resourceClass, $resourceMetadata, $operationName, $operation, $operation->getTypes()[0] ?? "#{$operation->getShortName()}", null);
  360.                 }
  361.             }
  362.         }
  364.         if (null !== $this->subresourceOperationFactory && !$this->resourceMetadataFactory instanceof ResourceMetadataCollectionFactoryInterface) {
  365.             foreach ($this->subresourceOperationFactory->create($resourceClass) as $operationId => $operation) {
  366.                 $subresourceMetadata = $this->resourceMetadataFactory->create($operation['resource_class']);
  367.                 $propertyMetadata = $this->propertyMetadataFactory->create(end($operation['identifiers'])[0], $operation['property']);
  368.                 $hydraOperations[] = $this->getHydraOperation($resourceClass, $subresourceMetadata, $operation['route_name'], $operation, "#{$subresourceMetadata->getShortName()}", OperationType::SUBRESOURCE, $propertyMetadata->getSubresource());
  369.             }
  370.         }
  372.         return $hydraOperations;
  373.     }
  375.     /**
  376.      * Gets and populates if applicable a Hydra operation.
  377.      *
  378.      * @param ResourceMetadata|ApiResource $resourceMetadata
  379.      * @param SubresourceMetadata          $subresourceMetadata
  380.      * @param array|HttpOperation          $operation
  381.      */
  382.     private function getHydraOperation(string $resourceClass, $resourceMetadata, string $operationName, $operation, string $prefixedShortName, ?string $operationType = null, SubresourceMetadata $subresourceMetadata = null): array
  383.     {
  384.         if ($operation instanceof HttpOperation) {
  385.             $method = $operation->getMethod() ?: HttpOperation::METHOD_GET;
  386.         } elseif ($this->operationMethodResolver) {
  387.             if (OperationType::COLLECTION === $operationType) {
  388.                 $method = $this->operationMethodResolver->getCollectionOperationMethod($resourceClass, $operationName);
  389.             } elseif (OperationType::ITEM === $operationType) {
  390.                 $method = $this->operationMethodResolver->getItemOperationMethod($resourceClass, $operationName);
  391.             } else {
  392.                 $method = 'GET';
  393.             }
  394.         } else {
  395.             $method = $resourceMetadata->getTypedOperationAttribute($operationType, $operationName, 'method', 'GET');
  396.         }
  398.         $hydraOperation = $operation instanceof HttpOperation ? ($operation->getHydraContext() ?? []) : ($operation['hydra_context'] ?? []);
  399.         if ($operation instanceof HttpOperation ? $operation->getDeprecationReason() : $resourceMetadata->getTypedOperationAttribute($operationType, $operationName, 'deprecation_reason', null, true)) {
  400.             $hydraOperation['owl:deprecated'] = true;
  401.         }
  403.         if ($operation instanceof HttpOperation) {
  404.             $shortName = $operation->getShortName();
  405.             $inputMetadata = $operation->getInput() ?? [];
  406.             $outputMetadata = $operation->getOutput() ?? [];
  407.             $operationType = $operation instanceof CollectionOperationInterface ? OperationType::COLLECTION : OperationType::ITEM;
  408.         } else {
  409.             $shortName = $resourceMetadata->getShortName();
  410.             $inputMetadata = $resourceMetadata->getTypedOperationAttribute($operationType, $operationName, 'input', ['class' => false]);
  411.             $outputMetadata = $resourceMetadata->getTypedOperationAttribute($operationType, $operationName, 'output', ['class' => false]);
  412.         }
  414.         $inputClass = \array_key_exists('class', $inputMetadata) ? $inputMetadata['class'] : false;
  415.         $outputClass = \array_key_exists('class', $outputMetadata) ? $outputMetadata['class'] : false;
  417.         if ('GET' === $method && OperationType::COLLECTION === $operationType) {
  418.             $hydraOperation += [
  419.                 '@type' => ['hydra:Operation', 'schema:FindAction'],
  420.                 'hydra:title' => "Retrieves the collection of $shortName resources.",
  421.                 'returns' => 'hydra:Collection',
  422.             ];
  423.         } elseif ('GET' === $method && OperationType::SUBRESOURCE === $operationType) {
  424.             $hydraOperation += [
  425.                 '@type' => ['hydra:Operation', 'schema:FindAction'],
  426.                 'hydra:title' => $subresourceMetadata && $subresourceMetadata->isCollection() ? "Retrieves the collection of $shortName resources." : "Retrieves a $shortName resource.",
  427.                 'returns' => null === $outputClass ? 'owl:Nothing' : "#$shortName",
  428.             ];
  429.         } elseif ('GET' === $method) {
  430.             $hydraOperation += [
  431.                 '@type' => ['hydra:Operation', 'schema:FindAction'],
  432.                 'hydra:title' => "Retrieves a $shortName resource.",
  433.                 'returns' => null === $outputClass ? 'owl:Nothing' : $prefixedShortName,
  434.             ];
  435.         } elseif ('PATCH' === $method) {
  436.             $hydraOperation += [
  437.                 '@type' => 'hydra:Operation',
  438.                 'hydra:title' => "Updates the $shortName resource.",
  439.                 'returns' => null === $outputClass ? 'owl:Nothing' : $prefixedShortName,
  440.                 'expects' => null === $inputClass ? 'owl:Nothing' : $prefixedShortName,
  441.             ];
  442.         } elseif ('POST' === $method) {
  443.             $hydraOperation += [
  444.                 '@type' => ['hydra:Operation', 'schema:CreateAction'],
  445.                 'hydra:title' => "Creates a $shortName resource.",
  446.                 'returns' => null === $outputClass ? 'owl:Nothing' : $prefixedShortName,
  447.                 'expects' => null === $inputClass ? 'owl:Nothing' : $prefixedShortName,
  448.             ];
  449.         } elseif ('PUT' === $method) {
  450.             $hydraOperation += [
  451.                 '@type' => ['hydra:Operation', 'schema:ReplaceAction'],
  452.                 'hydra:title' => "Replaces the $shortName resource.",
  453.                 'returns' => null === $outputClass ? 'owl:Nothing' : $prefixedShortName,
  454.                 'expects' => null === $inputClass ? 'owl:Nothing' : $prefixedShortName,
  455.             ];
  456.         } elseif ('DELETE' === $method) {
  457.             $hydraOperation += [
  458.                 '@type' => ['hydra:Operation', 'schema:DeleteAction'],
  459.                 'hydra:title' => "Deletes the $shortName resource.",
  460.                 'returns' => 'owl:Nothing',
  461.             ];
  462.         }
  464.         $hydraOperation['hydra:method'] ?? $hydraOperation['hydra:method'] = $method;
  466.         if (!isset($hydraOperation['rdfs:label']) && isset($hydraOperation['hydra:title'])) {
  467.             $hydraOperation['rdfs:label'] = $hydraOperation['hydra:title'];
  468.         }
  470.         ksort($hydraOperation);
  472.         return $hydraOperation;
  473.     }
  475.     /**
  476.      * Gets the range of the property.
  477.      *
  478.      * @param ApiProperty|PropertyMetadata $propertyMetadata
  479.      */
  480.     private function getRange($propertyMetadata): ?string
  481.     {
  482.         $jsonldContext = $propertyMetadata instanceof PropertyMetadata ? $propertyMetadata->getAttributes()['jsonld_context'] ?? [] : $propertyMetadata->getJsonldContext();
  484.         if (isset($jsonldContext['@type'])) {
  485.             return $jsonldContext['@type'];
  486.         }
  488.         // TODO: 3.0 support multiple types, default value of types will be [] instead of null
  489.         $type = $propertyMetadata instanceof PropertyMetadata ? $propertyMetadata->getType() : $propertyMetadata->getBuiltinTypes()[0] ?? null;
  490.         if (null === $type) {
  491.             return null;
  492.         }
  494.         if ($type->isCollection() && null !== $collectionType = method_exists(Type::class, 'getCollectionValueTypes') ? ($type->getCollectionValueTypes()[0] ?? null) : $type->getCollectionValueType()) {
  495.             $type = $collectionType;
  496.         }
  498.         switch ($type->getBuiltinType()) {
  499.             case Type::BUILTIN_TYPE_STRING:
  500.                 return 'xmls:string';
  501.             case Type::BUILTIN_TYPE_INT:
  502.                 return 'xmls:integer';
  503.             case Type::BUILTIN_TYPE_FLOAT:
  504.                 return 'xmls:decimal';
  505.             case Type::BUILTIN_TYPE_BOOL:
  506.                 return 'xmls:boolean';
  507.             case Type::BUILTIN_TYPE_OBJECT:
  508.                 if (null === $className = $type->getClassName()) {
  509.                     return null;
  510.                 }
  512.                 if (is_a($className, \DateTimeInterface::class, true)) {
  513.                     return 'xmls:dateTime';
  514.                 }
  516.                 if ($this->resourceClassResolver->isResourceClass($className)) {
  517.                     $resourceMetadata = $this->resourceMetadataFactory->create($className);
  518.                     if ($resourceMetadata instanceof ResourceMetadataCollection) {
  519.                         $operation = $resourceMetadata->getOperation();
  521.                         if (!$operation instanceof HttpOperation) {
  522.                             return "#{$operation->getShortName()}";
  523.                         }
  525.                         return $operation->getTypes()[0] ?? "#{$operation->getShortName()}";
  526.                     }
  528.                     return $resourceMetadata->getIri() ?? "#{$resourceMetadata->getShortName()}";
  529.                 }
  530.         }
  532.         return null;
  533.     }
  535.     /**
  536.      * Builds the classes array.
  537.      */
  538.     private function getClasses(array $entrypointProperties, array $classes): array
  539.     {
  540.         $classes[] = [
  541.             '@id' => '#Entrypoint',
  542.             '@type' => 'hydra:Class',
  543.             'hydra:title' => 'The API entrypoint',
  544.             'hydra:supportedProperty' => $entrypointProperties,
  545.             'hydra:supportedOperation' => [
  546.                 '@type' => 'hydra:Operation',
  547.                 'hydra:method' => 'GET',
  548.                 'rdfs:label' => 'The API entrypoint.',
  549.                 'returns' => '#EntryPoint',
  550.             ],
  551.         ];
  553.         // Constraint violation
  554.         $classes[] = [
  555.             '@id' => '#ConstraintViolation',
  556.             '@type' => 'hydra:Class',
  557.             'hydra:title' => 'A constraint violation',
  558.             'hydra:supportedProperty' => [
  559.                 [
  560.                     '@type' => 'hydra:SupportedProperty',
  561.                     'hydra:property' => [
  562.                         '@id' => '#ConstraintViolation/propertyPath',
  563.                         '@type' => 'rdf:Property',
  564.                         'rdfs:label' => 'propertyPath',
  565.                         'domain' => '#ConstraintViolation',
  566.                         'range' => 'xmls:string',
  567.                     ],
  568.                     'hydra:title' => 'propertyPath',
  569.                     'hydra:description' => 'The property path of the violation',
  570.                     'hydra:readable' => true,
  571.                     'hydra:writeable' => false,
  572.                 ],
  573.                 [
  574.                     '@type' => 'hydra:SupportedProperty',
  575.                     'hydra:property' => [
  576.                         '@id' => '#ConstraintViolation/message',
  577.                         '@type' => 'rdf:Property',
  578.                         'rdfs:label' => 'message',
  579.                         'domain' => '#ConstraintViolation',
  580.                         'range' => 'xmls:string',
  581.                     ],
  582.                     'hydra:title' => 'message',
  583.                     'hydra:description' => 'The message associated with the violation',
  584.                     'hydra:readable' => true,
  585.                     'hydra:writeable' => false,
  586.                 ],
  587.             ],
  588.         ];
  590.         // Constraint violation list
  591.         $classes[] = [
  592.             '@id' => '#ConstraintViolationList',
  593.             '@type' => 'hydra:Class',
  594.             'subClassOf' => 'hydra:Error',
  595.             'hydra:title' => 'A constraint violation list',
  596.             'hydra:supportedProperty' => [
  597.                 [
  598.                     '@type' => 'hydra:SupportedProperty',
  599.                     'hydra:property' => [
  600.                         '@id' => '#ConstraintViolationList/violations',
  601.                         '@type' => 'rdf:Property',
  602.                         'rdfs:label' => 'violations',
  603.                         'domain' => '#ConstraintViolationList',
  604.                         'range' => '#ConstraintViolation',
  605.                     ],
  606.                     'hydra:title' => 'violations',
  607.                     'hydra:description' => 'The violations',
  608.                     'hydra:readable' => true,
  609.                     'hydra:writeable' => false,
  610.                 ],
  611.             ],
  612.         ];
  614.         return $classes;
  615.     }
  617.     /**
  618.      * Gets a property definition.
  619.      *
  620.      * @param ApiProperty|PropertyMetadata $propertyMetadata
  621.      */
  622.     private function getProperty($propertyMetadata, string $propertyName, string $prefixedShortName, string $shortName): array
  623.     {
  624.         if ($propertyMetadata instanceof PropertyMetadata) {
  625.             $iri = $propertyMetadata->getIri();
  626.         } else {
  627.             if ($iri = $propertyMetadata->getIris()) {
  628.                 $iri = 1 === \count($iri) ? $iri[0] : $iri;
  629.             }
  630.         }
  632.         if (!isset($iri)) {
  633.             $iri = "#$shortName/$propertyName";
  634.         }
  636.         $propertyData = [
  637.             '@id' => $iri,
  638.             '@type' => false === $propertyMetadata->isReadableLink() ? 'hydra:Link' : 'rdf:Property',
  639.             'rdfs:label' => $propertyName,
  640.             'domain' => $prefixedShortName,
  641.         ];
  643.         // TODO: 3.0 support multiple types, default value of types will be [] instead of null
  644.         $type = $propertyMetadata instanceof PropertyMetadata ? $propertyMetadata->getType() : $propertyMetadata->getBuiltinTypes()[0] ?? null;
  646.         if (null !== $type && !$type->isCollection() && (null !== $className = $type->getClassName()) && $this->resourceClassResolver->isResourceClass($className)) {
  647.             $propertyData['owl:maxCardinality'] = 1;
  648.         }
  650.         $property = [
  651.             '@type' => 'hydra:SupportedProperty',
  652.             'hydra:property' => $propertyData,
  653.             'hydra:title' => $propertyName,
  654.             'hydra:required' => $propertyMetadata->isRequired(),
  655.             'hydra:readable' => $propertyMetadata->isReadable(),
  656.             'hydra:writeable' => $propertyMetadata->isWritable() || $propertyMetadata->isInitializable(),
  657.         ];
  659.         if (null !== $range = $this->getRange($propertyMetadata)) {
  660.             $property['hydra:property']['range'] = $range;
  661.         }
  663.         if (null !== $description = $propertyMetadata->getDescription()) {
  664.             $property['hydra:description'] = $description;
  665.         }
  667.         if ($deprecationReason = $propertyMetadata instanceof PropertyMetadata ? $propertyMetadata->getAttribute('deprecation_reason') : $propertyMetadata->getDeprecationReason()) {
  668.             $property['owl:deprecated'] = true;
  669.         }
  671.         return $property;
  672.     }
  674.     /**
  675.      * Computes the documentation.
  676.      */
  677.     private function computeDoc(Documentation $object, array $classes): array
  678.     {
  679.         $doc = ['@context' => $this->getContext(), '@id' => $this->urlGenerator->generate('api_doc', ['_format' => self::FORMAT]), '@type' => 'hydra:ApiDocumentation'];
  681.         if ('' !== $object->getTitle()) {
  682.             $doc['hydra:title'] = $object->getTitle();
  683.         }
  685.         if ('' !== $object->getDescription()) {
  686.             $doc['hydra:description'] = $object->getDescription();
  687.         }
  689.         $doc['hydra:entrypoint'] = $this->urlGenerator->generate('api_entrypoint');
  690.         $doc['hydra:supportedClass'] = $classes;
  692.         return $doc;
  693.     }
  695.     /**
  696.      * Builds the JSON-LD context for the API documentation.
  697.      */
  698.     private function getContext(): array
  699.     {
  700.         return [
  701.             '@vocab' => $this->urlGenerator->generate('api_doc', ['_format' => self::FORMAT], UrlGeneratorInterface::ABS_URL).'#',
  702.             'hydra' => ContextBuilderInterface::HYDRA_NS,
  703.             'rdf' => ContextBuilderInterface::RDF_NS,
  704.             'rdfs' => ContextBuilderInterface::RDFS_NS,
  705.             'xmls' => ContextBuilderInterface::XML_NS,
  706.             'owl' => ContextBuilderInterface::OWL_NS,
  707.             'schema' => ContextBuilderInterface::SCHEMA_ORG_NS,
  708.             'domain' => ['@id' => 'rdfs:domain', '@type' => '@id'],
  709.             'range' => ['@id' => 'rdfs:range', '@type' => '@id'],
  710.             'subClassOf' => ['@id' => 'rdfs:subClassOf', '@type' => '@id'],
  711.             'expects' => ['@id' => 'hydra:expects', '@type' => '@id'],
  712.             'returns' => ['@id' => 'hydra:returns', '@type' => '@id'],
  713.         ];
  714.     }
  716.     /**
  717.      * {@inheritdoc}
  718.      */
  719.     public function supportsNormalization($data, $format = null, array $context = []): bool
  720.     {
  721.         return self::FORMAT === $format && $data instanceof Documentation;
  722.     }
  724.     /**
  725.      * {@inheritdoc}
  726.      */
  727.     public function hasCacheableSupportsMethod(): bool
  728.     {
  729.         return true;
  730.     }
  731. }
  733. class_alias(DocumentationNormalizer::class, \ApiPlatform\Core\Hydra\Serializer\DocumentationNormalizer::class);