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

  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\Documentation\Documentation;
  19. use ApiPlatform\JsonLd\ContextBuilderInterface;
  20. use ApiPlatform\Metadata\ApiProperty;
  21. use ApiPlatform\Metadata\ApiResource;
  22. use ApiPlatform\Metadata\CollectionOperationInterface;
  23. use ApiPlatform\Metadata\HttpOperation;
  24. use ApiPlatform\Metadata\Operation;
  25. use ApiPlatform\Metadata\Property\Factory\PropertyMetadataFactoryInterface;
  26. use ApiPlatform\Metadata\Property\Factory\PropertyNameCollectionFactoryInterface;
  27. use ApiPlatform\Metadata\Resource\Factory\ResourceMetadataCollectionFactoryInterface;
  28. use ApiPlatform\Metadata\Resource\ResourceMetadataCollection;
  29. use Symfony\Component\PropertyInfo\Type;
  30. use Symfony\Component\Serializer\NameConverter\NameConverterInterface;
  31. use Symfony\Component\Serializer\Normalizer\AbstractNormalizer;
  32. use Symfony\Component\Serializer\Normalizer\CacheableSupportsMethodInterface;
  33. use Symfony\Component\Serializer\Normalizer\NormalizerInterface;
  35. /**
  36.  * Creates a machine readable Hydra API documentation.
  37.  *
  38.  * @author Kévin Dunglas <dunglas@gmail.com>
  39.  */
  40. final class DocumentationNormalizer implements NormalizerInterface, CacheableSupportsMethodInterface
  41. {
  42.     public const FORMAT = 'jsonld';
  44.     public function __construct(private readonly ResourceMetadataCollectionFactoryInterface $resourceMetadataFactory, private readonly PropertyNameCollectionFactoryInterface $propertyNameCollectionFactory, private readonly PropertyMetadataFactoryInterface $propertyMetadataFactory, private readonly ResourceClassResolverInterface $resourceClassResolver, private readonly UrlGeneratorInterface $urlGenerator, private readonly ?NameConverterInterface $nameConverter = null)
  45.     {
  46.     }
  48.     /**
  49.      * {@inheritdoc}
  50.      */
  51.     public function normalize(mixed $object, string $format = null, array $context = []): array|string|int|float|bool|\ArrayObject|null
  52.     {
  53.         $classes = [];
  54.         $entrypointProperties = [];
  56.         foreach ($object->getResourceNameCollection() as $resourceClass) {
  57.             $resourceMetadataCollection = $this->resourceMetadataFactory->create($resourceClass);
  59.             $resourceMetadata = $resourceMetadataCollection[0];
  60.             $shortName = $resourceMetadata->getShortName();
  61.             $prefixedShortName = $resourceMetadata->getTypes()[0] ?? "#$shortName";
  62.             $this->populateEntrypointProperties($resourceMetadata, $shortName, $prefixedShortName, $entrypointProperties, $resourceMetadataCollection);
  63.             $classes[] = $this->getClass($resourceClass, $resourceMetadata, $shortName, $prefixedShortName, $context, $resourceMetadataCollection);
  64.         }
  66.         return $this->computeDoc($object, $this->getClasses($entrypointProperties, $classes));
  67.     }
  69.     /**
  70.      * Populates entrypoint properties.
  71.      */
  72.     private function populateEntrypointProperties(ApiResource $resourceMetadata, string $shortName, string $prefixedShortName, array &$entrypointProperties, ?ResourceMetadataCollection $resourceMetadataCollection = null): void
  73.     {
  74.         $hydraCollectionOperations = $this->getHydraOperations(true, $resourceMetadataCollection);
  75.         if (empty($hydraCollectionOperations)) {
  76.             return;
  77.         }
  79.         $entrypointProperty = [
  80.             '@type' => 'hydra:SupportedProperty',
  81.             'hydra:property' => [
  82.                 '@id' => sprintf('#Entrypoint/%s', lcfirst($shortName)),
  83.                 '@type' => 'hydra:Link',
  84.                 'domain' => '#Entrypoint',
  85.                 'rdfs:label' => "The collection of $shortName resources",
  86.                 'rdfs:range' => [
  87.                     ['@id' => 'hydra:Collection'],
  88.                     [
  89.                         'owl:equivalentClass' => [
  90.                             'owl:onProperty' => ['@id' => 'hydra:member'],
  91.                             'owl:allValuesFrom' => ['@id' => $prefixedShortName],
  92.                         ],
  93.                     ],
  94.                 ],
  95.                 'hydra:supportedOperation' => $hydraCollectionOperations,
  96.             ],
  97.             'hydra:title' => "The collection of $shortName resources",
  98.             'hydra:readable' => true,
  99.             'hydra:writeable' => false,
  100.         ];
  102.         if ($resourceMetadata->getDeprecationReason()) {
  103.             $entrypointProperty['owl:deprecated'] = true;
  104.         }
  106.         $entrypointProperties[] = $entrypointProperty;
  107.     }
  109.     /**
  110.      * Gets a Hydra class.
  111.      */
  112.     private function getClass(string $resourceClass, ApiResource $resourceMetadata, string $shortName, string $prefixedShortName, array $context, ?ResourceMetadataCollection $resourceMetadataCollection = null): array
  113.     {
  114.         $description = $resourceMetadata->getDescription();
  115.         $isDeprecated = $resourceMetadata->getDeprecationReason();
  117.         $class = [
  118.             '@id' => $prefixedShortName,
  119.             '@type' => 'hydra:Class',
  120.             'rdfs:label' => $shortName,
  121.             'hydra:title' => $shortName,
  122.             'hydra:supportedProperty' => $this->getHydraProperties($resourceClass, $resourceMetadata, $shortName, $prefixedShortName, $context),
  123.             'hydra:supportedOperation' => $this->getHydraOperations(false, $resourceMetadataCollection),
  124.         ];
  126.         if (null !== $description) {
  127.             $class['hydra:description'] = $description;
  128.         }
  130.         if ($isDeprecated) {
  131.             $class['owl:deprecated'] = true;
  132.         }
  134.         return $class;
  135.     }
  137.     /**
  138.      * Creates context for property metatata factories.
  139.      */
  140.     private function getPropertyMetadataFactoryContext(ApiResource $resourceMetadata): array
  141.     {
  142.         $normalizationGroups = $resourceMetadata->getNormalizationContext()[AbstractNormalizer::GROUPS] ?? null;
  143.         $denormalizationGroups = $resourceMetadata->getDenormalizationContext()[AbstractNormalizer::GROUPS] ?? null;
  144.         $propertyContext = [
  145.             'normalization_groups' => $normalizationGroups,
  146.             'denormalization_groups' => $denormalizationGroups,
  147.         ];
  148.         $propertyNameContext = [];
  150.         if ($normalizationGroups) {
  151.             $propertyNameContext['serializer_groups'] = $normalizationGroups;
  152.         }
  154.         if (!$denormalizationGroups) {
  155.             return [$propertyNameContext, $propertyContext];
  156.         }
  158.         if (!isset($propertyNameContext['serializer_groups'])) {
  159.             $propertyNameContext['serializer_groups'] = $denormalizationGroups;
  161.             return [$propertyNameContext, $propertyContext];
  162.         }
  164.         foreach ($denormalizationGroups as $group) {
  165.             $propertyNameContext['serializer_groups'][] = $group;
  166.         }
  168.         return [$propertyNameContext, $propertyContext];
  169.     }
  171.     /**
  172.      * Gets Hydra properties.
  173.      */
  174.     private function getHydraProperties(string $resourceClass, ApiResource $resourceMetadata, string $shortName, string $prefixedShortName, array $context): array
  175.     {
  176.         $classes = [];
  178.         $classes[$resourceClass] = true;
  179.         foreach ($resourceMetadata->getOperations() as $operation) {
  180.             /** @var Operation $operation */
  181.             if (!$operation instanceof CollectionOperationInterface) {
  182.                 continue;
  183.             }
  185.             $inputMetadata = $operation->getInput();
  186.             if (null !== $inputClass = $inputMetadata['class'] ?? null) {
  187.                 $classes[$inputClass] = true;
  188.             }
  190.             $outputMetadata = $operation->getOutput();
  191.             if (null !== $outputClass = $outputMetadata['class'] ?? null) {
  192.                 $classes[$outputClass] = true;
  193.             }
  194.         }
  196.         /** @var string[] $classes */
  197.         $classes = array_keys($classes);
  198.         $properties = [];
  199.         [$propertyNameContext, $propertyContext] = $this->getPropertyMetadataFactoryContext($resourceMetadata);
  201.         foreach ($classes as $class) {
  202.             foreach ($this->propertyNameCollectionFactory->create($class, $propertyNameContext) as $propertyName) {
  203.                 $propertyMetadata = $this->propertyMetadataFactory->create($class, $propertyName, $propertyContext);
  205.                 if (true === $propertyMetadata->isIdentifier() && false === $propertyMetadata->isWritable()) {
  206.                     continue;
  207.                 }
  209.                 if ($this->nameConverter) {
  210.                     $propertyName = $this->nameConverter->normalize($propertyName, $class, self::FORMAT, $context);
  211.                 }
  213.                 $properties[] = $this->getProperty($propertyMetadata, $propertyName, $prefixedShortName, $shortName);
  214.             }
  215.         }
  217.         return $properties;
  218.     }
  220.     /**
  221.      * Gets Hydra operations.
  222.      */
  223.     private function getHydraOperations(bool $collection, ?ResourceMetadataCollection $resourceMetadataCollection = null): array
  224.     {
  225.         $hydraOperations = [];
  226.         foreach ($resourceMetadataCollection as $resourceMetadata) {
  227.             foreach ($resourceMetadata->getOperations() as $operation) {
  228.                 if ((HttpOperation::METHOD_POST === $operation->getMethod() || $operation instanceof CollectionOperationInterface) !== $collection) {
  229.                     continue;
  230.                 }
  232.                 $hydraOperations[] = $this->getHydraOperation($operation, $operation->getTypes()[0] ?? "#{$operation->getShortName()}");
  233.             }
  234.         }
  236.         return $hydraOperations;
  237.     }
  239.     /**
  240.      * Gets and populates if applicable a Hydra operation.
  241.      */
  242.     private function getHydraOperation(HttpOperation $operation, string $prefixedShortName): array
  243.     {
  244.         $method = $operation->getMethod() ?: HttpOperation::METHOD_GET;
  246.         $hydraOperation = $operation->getHydraContext() ?? [];
  247.         if ($operation->getDeprecationReason()) {
  248.             $hydraOperation['owl:deprecated'] = true;
  249.         }
  251.         $shortName = $operation->getShortName();
  252.         $inputMetadata = $operation->getInput() ?? [];
  253.         $outputMetadata = $operation->getOutput() ?? [];
  255.         $inputClass = \array_key_exists('class', $inputMetadata) ? $inputMetadata['class'] : false;
  256.         $outputClass = \array_key_exists('class', $outputMetadata) ? $outputMetadata['class'] : false;
  258.         if ('GET' === $method && $operation instanceof CollectionOperationInterface) {
  259.             $hydraOperation += [
  260.                 '@type' => ['hydra:Operation', 'schema:FindAction'],
  261.                 'hydra:title' => "Retrieves the collection of $shortName resources.",
  262.                 'returns' => null === $outputClass ? 'owl:Nothing' : 'hydra:Collection',
  263.             ];
  264.         } elseif ('GET' === $method) {
  265.             $hydraOperation += [
  266.                 '@type' => ['hydra:Operation', 'schema:FindAction'],
  267.                 'hydra:title' => "Retrieves a $shortName resource.",
  268.                 'returns' => null === $outputClass ? 'owl:Nothing' : $prefixedShortName,
  269.             ];
  270.         } elseif ('PATCH' === $method) {
  271.             $hydraOperation += [
  272.                 '@type' => 'hydra:Operation',
  273.                 'hydra:title' => "Updates the $shortName resource.",
  274.                 'returns' => null === $outputClass ? 'owl:Nothing' : $prefixedShortName,
  275.                 'expects' => null === $inputClass ? 'owl:Nothing' : $prefixedShortName,
  276.             ];
  277.         } elseif ('POST' === $method) {
  278.             $hydraOperation += [
  279.                 '@type' => ['hydra:Operation', 'schema:CreateAction'],
  280.                 'hydra:title' => "Creates a $shortName resource.",
  281.                 'returns' => null === $outputClass ? 'owl:Nothing' : $prefixedShortName,
  282.                 'expects' => null === $inputClass ? 'owl:Nothing' : $prefixedShortName,
  283.             ];
  284.         } elseif ('PUT' === $method) {
  285.             $hydraOperation += [
  286.                 '@type' => ['hydra:Operation', 'schema:ReplaceAction'],
  287.                 'hydra:title' => "Replaces the $shortName resource.",
  288.                 'returns' => null === $outputClass ? 'owl:Nothing' : $prefixedShortName,
  289.                 'expects' => null === $inputClass ? 'owl:Nothing' : $prefixedShortName,
  290.             ];
  291.         } elseif ('DELETE' === $method) {
  292.             $hydraOperation += [
  293.                 '@type' => ['hydra:Operation', 'schema:DeleteAction'],
  294.                 'hydra:title' => "Deletes the $shortName resource.",
  295.                 'returns' => 'owl:Nothing',
  296.             ];
  297.         }
  299.         $hydraOperation['hydra:method'] ?? $hydraOperation['hydra:method'] = $method;
  301.         if (!isset($hydraOperation['rdfs:label']) && isset($hydraOperation['hydra:title'])) {
  302.             $hydraOperation['rdfs:label'] = $hydraOperation['hydra:title'];
  303.         }
  305.         ksort($hydraOperation);
  307.         return $hydraOperation;
  308.     }
  310.     /**
  311.      * Gets the range of the property.
  312.      */
  313.     private function getRange(ApiProperty $propertyMetadata): ?string
  314.     {
  315.         $jsonldContext = $propertyMetadata->getJsonldContext();
  317.         if (isset($jsonldContext['@type'])) {
  318.             return $jsonldContext['@type'];
  319.         }
  321.         // TODO: 3.0 support multiple types, default value of types will be [] instead of null
  322.         $type = $propertyMetadata->getBuiltinTypes()[0] ?? null;
  323.         if (null === $type) {
  324.             return null;
  325.         }
  327.         if ($type->isCollection() && null !== $collectionType = $type->getCollectionValueTypes()[0] ?? null) {
  328.             $type = $collectionType;
  329.         }
  331.         switch ($type->getBuiltinType()) {
  332.             case Type::BUILTIN_TYPE_STRING:
  333.                 return 'xmls:string';
  334.             case Type::BUILTIN_TYPE_INT:
  335.                 return 'xmls:integer';
  336.             case Type::BUILTIN_TYPE_FLOAT:
  337.                 return 'xmls:decimal';
  338.             case Type::BUILTIN_TYPE_BOOL:
  339.                 return 'xmls:boolean';
  340.             case Type::BUILTIN_TYPE_OBJECT:
  341.                 if (null === $className = $type->getClassName()) {
  342.                     return null;
  343.                 }
  345.                 if (is_a($className, \DateTimeInterface::class, true)) {
  346.                     return 'xmls:dateTime';
  347.                 }
  349.                 if ($this->resourceClassResolver->isResourceClass($className)) {
  350.                     $resourceMetadata = $this->resourceMetadataFactory->create($className);
  351.                     $operation = $resourceMetadata->getOperation();
  353.                     if (!$operation instanceof HttpOperation) {
  354.                         return "#{$operation->getShortName()}";
  355.                     }
  357.                     return $operation->getTypes()[0] ?? "#{$operation->getShortName()}";
  358.                 }
  359.         }
  361.         return null;
  362.     }
  364.     /**
  365.      * Builds the classes array.
  366.      */
  367.     private function getClasses(array $entrypointProperties, array $classes): array
  368.     {
  369.         $classes[] = [
  370.             '@id' => '#Entrypoint',
  371.             '@type' => 'hydra:Class',
  372.             'hydra:title' => 'The API entrypoint',
  373.             'hydra:supportedProperty' => $entrypointProperties,
  374.             'hydra:supportedOperation' => [
  375.                 '@type' => 'hydra:Operation',
  376.                 'hydra:method' => 'GET',
  377.                 'rdfs:label' => 'The API entrypoint.',
  378.                 'returns' => '#EntryPoint',
  379.             ],
  380.         ];
  382.         // Constraint violation
  383.         $classes[] = [
  384.             '@id' => '#ConstraintViolation',
  385.             '@type' => 'hydra:Class',
  386.             'hydra:title' => 'A constraint violation',
  387.             'hydra:supportedProperty' => [
  388.                 [
  389.                     '@type' => 'hydra:SupportedProperty',
  390.                     'hydra:property' => [
  391.                         '@id' => '#ConstraintViolation/propertyPath',
  392.                         '@type' => 'rdf:Property',
  393.                         'rdfs:label' => 'propertyPath',
  394.                         'domain' => '#ConstraintViolation',
  395.                         'range' => 'xmls:string',
  396.                     ],
  397.                     'hydra:title' => 'propertyPath',
  398.                     'hydra:description' => 'The property path of the violation',
  399.                     'hydra:readable' => true,
  400.                     'hydra:writeable' => false,
  401.                 ],
  402.                 [
  403.                     '@type' => 'hydra:SupportedProperty',
  404.                     'hydra:property' => [
  405.                         '@id' => '#ConstraintViolation/message',
  406.                         '@type' => 'rdf:Property',
  407.                         'rdfs:label' => 'message',
  408.                         'domain' => '#ConstraintViolation',
  409.                         'range' => 'xmls:string',
  410.                     ],
  411.                     'hydra:title' => 'message',
  412.                     'hydra:description' => 'The message associated with the violation',
  413.                     'hydra:readable' => true,
  414.                     'hydra:writeable' => false,
  415.                 ],
  416.             ],
  417.         ];
  419.         // Constraint violation list
  420.         $classes[] = [
  421.             '@id' => '#ConstraintViolationList',
  422.             '@type' => 'hydra:Class',
  423.             'subClassOf' => 'hydra:Error',
  424.             'hydra:title' => 'A constraint violation list',
  425.             'hydra:supportedProperty' => [
  426.                 [
  427.                     '@type' => 'hydra:SupportedProperty',
  428.                     'hydra:property' => [
  429.                         '@id' => '#ConstraintViolationList/violations',
  430.                         '@type' => 'rdf:Property',
  431.                         'rdfs:label' => 'violations',
  432.                         'domain' => '#ConstraintViolationList',
  433.                         'range' => '#ConstraintViolation',
  434.                     ],
  435.                     'hydra:title' => 'violations',
  436.                     'hydra:description' => 'The violations',
  437.                     'hydra:readable' => true,
  438.                     'hydra:writeable' => false,
  439.                 ],
  440.             ],
  441.         ];
  443.         return $classes;
  444.     }
  446.     /**
  447.      * Gets a property definition.
  448.      */
  449.     private function getProperty(ApiProperty $propertyMetadata, string $propertyName, string $prefixedShortName, string $shortName): array
  450.     {
  451.         if ($iri = $propertyMetadata->getIris()) {
  452.             $iri = 1 === (is_countable($iri) ? \count($iri) : 0) ? $iri[0] : $iri;
  453.         }
  455.         if (!isset($iri)) {
  456.             $iri = "#$shortName/$propertyName";
  457.         }
  459.         $propertyData = [
  460.             '@id' => $iri,
  461.             '@type' => false === $propertyMetadata->isReadableLink() ? 'hydra:Link' : 'rdf:Property',
  462.             'rdfs:label' => $propertyName,
  463.             'domain' => $prefixedShortName,
  464.         ];
  466.         // TODO: 3.0 support multiple types, default value of types will be [] instead of null
  467.         $type = $propertyMetadata->getBuiltinTypes()[0] ?? null;
  469.         if (null !== $type && !$type->isCollection() && (null !== $className = $type->getClassName()) && $this->resourceClassResolver->isResourceClass($className)) {
  470.             $propertyData['owl:maxCardinality'] = 1;
  471.         }
  473.         $property = [
  474.             '@type' => 'hydra:SupportedProperty',
  475.             'hydra:property' => $propertyData,
  476.             'hydra:title' => $propertyName,
  477.             'hydra:required' => $propertyMetadata->isRequired(),
  478.             'hydra:readable' => $propertyMetadata->isReadable(),
  479.             'hydra:writeable' => $propertyMetadata->isWritable() || $propertyMetadata->isInitializable(),
  480.         ];
  482.         if (null !== $range = $this->getRange($propertyMetadata)) {
  483.             $property['hydra:property']['range'] = $range;
  484.         }
  486.         if (null !== $description = $propertyMetadata->getDescription()) {
  487.             $property['hydra:description'] = $description;
  488.         }
  490.         if ($deprecationReason = $propertyMetadata->getDeprecationReason()) {
  491.             $property['owl:deprecated'] = true;
  492.         }
  494.         return $property;
  495.     }
  497.     /**
  498.      * Computes the documentation.
  499.      */
  500.     private function computeDoc(Documentation $object, array $classes): array
  501.     {
  502.         $doc = ['@context' => $this->getContext(), '@id' => $this->urlGenerator->generate('api_doc', ['_format' => self::FORMAT]), '@type' => 'hydra:ApiDocumentation'];
  504.         if ('' !== $object->getTitle()) {
  505.             $doc['hydra:title'] = $object->getTitle();
  506.         }
  508.         if ('' !== $object->getDescription()) {
  509.             $doc['hydra:description'] = $object->getDescription();
  510.         }
  512.         $doc['hydra:entrypoint'] = $this->urlGenerator->generate('api_entrypoint');
  513.         $doc['hydra:supportedClass'] = $classes;
  515.         return $doc;
  516.     }
  518.     /**
  519.      * Builds the JSON-LD context for the API documentation.
  520.      */
  521.     private function getContext(): array
  522.     {
  523.         return [
  524.             '@vocab' => $this->urlGenerator->generate('api_doc', ['_format' => self::FORMAT], UrlGeneratorInterface::ABS_URL).'#',
  525.             'hydra' => ContextBuilderInterface::HYDRA_NS,
  526.             'rdf' => ContextBuilderInterface::RDF_NS,
  527.             'rdfs' => ContextBuilderInterface::RDFS_NS,
  528.             'xmls' => ContextBuilderInterface::XML_NS,
  529.             'owl' => ContextBuilderInterface::OWL_NS,
  530.             'schema' => ContextBuilderInterface::SCHEMA_ORG_NS,
  531.             'domain' => ['@id' => 'rdfs:domain', '@type' => '@id'],
  532.             'range' => ['@id' => 'rdfs:range', '@type' => '@id'],
  533.             'subClassOf' => ['@id' => 'rdfs:subClassOf', '@type' => '@id'],
  534.             'expects' => ['@id' => 'hydra:expects', '@type' => '@id'],
  535.             'returns' => ['@id' => 'hydra:returns', '@type' => '@id'],
  536.         ];
  537.     }
  539.     /**
  540.      * {@inheritdoc}
  541.      */
  542.     public function supportsNormalization(mixed $data, string $format = null, array $context = []): bool
  543.     {
  544.         return self::FORMAT === $format && $data instanceof Documentation;
  545.     }
  547.     public function hasCacheableSupportsMethod(): bool
  548.     {
  549.         return true;
  550.     }
  551. }