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

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. * @param mixed|null $format
  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 array|HttpOperation $operation
  380. */
  381. private function getHydraOperation(string $resourceClass, $resourceMetadata, string $operationName, $operation, string $prefixedShortName, string $operationType = null, SubresourceMetadata $subresourceMetadata = null): array
  382. {
  383. if ($operation instanceof HttpOperation) {
  384. $method = $operation->getMethod() ?: HttpOperation::METHOD_GET;
  385. } elseif ($this->operationMethodResolver) {
  386. if (OperationType::COLLECTION === $operationType) {
  387. $method = $this->operationMethodResolver->getCollectionOperationMethod($resourceClass, $operationName);
  388. } elseif (OperationType::ITEM === $operationType) {
  389. $method = $this->operationMethodResolver->getItemOperationMethod($resourceClass, $operationName);
  390. } else {
  391. $method = 'GET';
  392. }
  393. } else {
  394. $method = $resourceMetadata->getTypedOperationAttribute($operationType, $operationName, 'method', 'GET');
  395. }
  397. $hydraOperation = $operation instanceof HttpOperation ? ($operation->getHydraContext() ?? []) : ($operation['hydra_context'] ?? []);
  398. if ($operation instanceof HttpOperation ? $operation->getDeprecationReason() : $resourceMetadata->getTypedOperationAttribute($operationType, $operationName, 'deprecation_reason', null, true)) {
  399. $hydraOperation['owl:deprecated'] = true;
  400. }
  402. if ($operation instanceof HttpOperation) {
  403. $shortName = $operation->getShortName();
  404. $inputMetadata = $operation->getInput() ?? [];
  405. $outputMetadata = $operation->getOutput() ?? [];
  406. $operationType = $operation instanceof CollectionOperationInterface ? OperationType::COLLECTION : OperationType::ITEM;
  407. } else {
  408. $shortName = $resourceMetadata->getShortName();
  409. $inputMetadata = $resourceMetadata->getTypedOperationAttribute($operationType, $operationName, 'input', ['class' => false]);
  410. $outputMetadata = $resourceMetadata->getTypedOperationAttribute($operationType, $operationName, 'output', ['class' => false]);
  411. }
  413. $inputClass = \array_key_exists('class', $inputMetadata) ? $inputMetadata['class'] : false;
  414. $outputClass = \array_key_exists('class', $outputMetadata) ? $outputMetadata['class'] : false;
  416. if ('GET' === $method && OperationType::COLLECTION === $operationType) {
  417. $hydraOperation += [
  418. '@type' => ['hydra:Operation', 'schema:FindAction'],
  419. 'hydra:title' => "Retrieves the collection of $shortName resources.",
  420. 'returns' => 'hydra:Collection',
  421. ];
  422. } elseif ('GET' === $method && OperationType::SUBRESOURCE === $operationType) {
  423. $hydraOperation += [
  424. '@type' => ['hydra:Operation', 'schema:FindAction'],
  425. 'hydra:title' => $subresourceMetadata && $subresourceMetadata->isCollection() ? "Retrieves the collection of $shortName resources." : "Retrieves a $shortName resource.",
  426. 'returns' => null === $outputClass ? 'owl:Nothing' : "#$shortName",
  427. ];
  428. } elseif ('GET' === $method) {
  429. $hydraOperation += [
  430. '@type' => ['hydra:Operation', 'schema:FindAction'],
  431. 'hydra:title' => "Retrieves a $shortName resource.",
  432. 'returns' => null === $outputClass ? 'owl:Nothing' : $prefixedShortName,
  433. ];
  434. } elseif ('PATCH' === $method) {
  435. $hydraOperation += [
  436. '@type' => 'hydra:Operation',
  437. 'hydra:title' => "Updates the $shortName resource.",
  438. 'returns' => null === $outputClass ? 'owl:Nothing' : $prefixedShortName,
  439. 'expects' => null === $inputClass ? 'owl:Nothing' : $prefixedShortName,
  440. ];
  441. } elseif ('POST' === $method) {
  442. $hydraOperation += [
  443. '@type' => ['hydra:Operation', 'schema:CreateAction'],
  444. 'hydra:title' => "Creates a $shortName resource.",
  445. 'returns' => null === $outputClass ? 'owl:Nothing' : $prefixedShortName,
  446. 'expects' => null === $inputClass ? 'owl:Nothing' : $prefixedShortName,
  447. ];
  448. } elseif ('PUT' === $method) {
  449. $hydraOperation += [
  450. '@type' => ['hydra:Operation', 'schema:ReplaceAction'],
  451. 'hydra:title' => "Replaces the $shortName resource.",
  452. 'returns' => null === $outputClass ? 'owl:Nothing' : $prefixedShortName,
  453. 'expects' => null === $inputClass ? 'owl:Nothing' : $prefixedShortName,
  454. ];
  455. } elseif ('DELETE' === $method) {
  456. $hydraOperation += [
  457. '@type' => ['hydra:Operation', 'schema:DeleteAction'],
  458. 'hydra:title' => "Deletes the $shortName resource.",
  459. 'returns' => 'owl:Nothing',
  460. ];
  461. }
  463. $hydraOperation['hydra:method'] ?? $hydraOperation['hydra:method'] = $method;
  465. if (!isset($hydraOperation['rdfs:label']) && isset($hydraOperation['hydra:title'])) {
  466. $hydraOperation['rdfs:label'] = $hydraOperation['hydra:title'];
  467. }
  469. ksort($hydraOperation);
  471. return $hydraOperation;
  472. }
  474. /**
  475. * Gets the range of the property.
  476. *
  477. * @param ApiProperty|PropertyMetadata $propertyMetadata
  478. */
  479. private function getRange($propertyMetadata): ?string
  480. {
  481. $jsonldContext = $propertyMetadata instanceof PropertyMetadata ? $propertyMetadata->getAttributes()['jsonld_context'] ?? [] : $propertyMetadata->getJsonldContext();
  483. if (isset($jsonldContext['@type'])) {
  484. return $jsonldContext['@type'];
  485. }
  487. // TODO: 3.0 support multiple types, default value of types will be [] instead of null
  488. $type = $propertyMetadata instanceof PropertyMetadata ? $propertyMetadata->getType() : $propertyMetadata->getBuiltinTypes()[0] ?? null;
  489. if (null === $type) {
  490. return null;
  491. }
  493. if ($type->isCollection() && null !== $collectionType = method_exists(Type::class, 'getCollectionValueTypes') ? ($type->getCollectionValueTypes()[0] ?? null) : $type->getCollectionValueType()) {
  494. $type = $collectionType;
  495. }
  497. switch ($type->getBuiltinType()) {
  498. case Type::BUILTIN_TYPE_STRING:
  499. return 'xmls:string';
  500. case Type::BUILTIN_TYPE_INT:
  501. return 'xmls:integer';
  502. case Type::BUILTIN_TYPE_FLOAT:
  503. return 'xmls:decimal';
  504. case Type::BUILTIN_TYPE_BOOL:
  505. return 'xmls:boolean';
  506. case Type::BUILTIN_TYPE_OBJECT:
  507. if (null === $className = $type->getClassName()) {
  508. return null;
  509. }
  511. if (is_a($className, \DateTimeInterface::class, true)) {
  512. return 'xmls:dateTime';
  513. }
  515. if ($this->resourceClassResolver->isResourceClass($className)) {
  516. $resourceMetadata = $this->resourceMetadataFactory->create($className);
  517. if ($resourceMetadata instanceof ResourceMetadataCollection) {
  518. $operation = $resourceMetadata->getOperation();
  520. if (!$operation instanceof HttpOperation) {
  521. return "#{$operation->getShortName()}";
  522. }
  524. return $operation->getTypes()[0] ?? "#{$operation->getShortName()}";
  525. }
  527. return $resourceMetadata->getIri() ?? "#{$resourceMetadata->getShortName()}";
  528. }
  529. }
  531. return null;
  532. }
  534. /**
  535. * Builds the classes array.
  536. */
  537. private function getClasses(array $entrypointProperties, array $classes): array
  538. {
  539. $classes[] = [
  540. '@id' => '#Entrypoint',
  541. '@type' => 'hydra:Class',
  542. 'hydra:title' => 'The API entrypoint',
  543. 'hydra:supportedProperty' => $entrypointProperties,
  544. 'hydra:supportedOperation' => [
  545. '@type' => 'hydra:Operation',
  546. 'hydra:method' => 'GET',
  547. 'rdfs:label' => 'The API entrypoint.',
  548. 'returns' => '#EntryPoint',
  549. ],
  550. ];
  552. // Constraint violation
  553. $classes[] = [
  554. '@id' => '#ConstraintViolation',
  555. '@type' => 'hydra:Class',
  556. 'hydra:title' => 'A constraint violation',
  557. 'hydra:supportedProperty' => [
  558. [
  559. '@type' => 'hydra:SupportedProperty',
  560. 'hydra:property' => [
  561. '@id' => '#ConstraintViolation/propertyPath',
  562. '@type' => 'rdf:Property',
  563. 'rdfs:label' => 'propertyPath',
  564. 'domain' => '#ConstraintViolation',
  565. 'range' => 'xmls:string',
  566. ],
  567. 'hydra:title' => 'propertyPath',
  568. 'hydra:description' => 'The property path of the violation',
  569. 'hydra:readable' => true,
  570. 'hydra:writeable' => false,
  571. ],
  572. [
  573. '@type' => 'hydra:SupportedProperty',
  574. 'hydra:property' => [
  575. '@id' => '#ConstraintViolation/message',
  576. '@type' => 'rdf:Property',
  577. 'rdfs:label' => 'message',
  578. 'domain' => '#ConstraintViolation',
  579. 'range' => 'xmls:string',
  580. ],
  581. 'hydra:title' => 'message',
  582. 'hydra:description' => 'The message associated with the violation',
  583. 'hydra:readable' => true,
  584. 'hydra:writeable' => false,
  585. ],
  586. ],
  587. ];
  589. // Constraint violation list
  590. $classes[] = [
  591. '@id' => '#ConstraintViolationList',
  592. '@type' => 'hydra:Class',
  593. 'subClassOf' => 'hydra:Error',
  594. 'hydra:title' => 'A constraint violation list',
  595. 'hydra:supportedProperty' => [
  596. [
  597. '@type' => 'hydra:SupportedProperty',
  598. 'hydra:property' => [
  599. '@id' => '#ConstraintViolationList/violations',
  600. '@type' => 'rdf:Property',
  601. 'rdfs:label' => 'violations',
  602. 'domain' => '#ConstraintViolationList',
  603. 'range' => '#ConstraintViolation',
  604. ],
  605. 'hydra:title' => 'violations',
  606. 'hydra:description' => 'The violations',
  607. 'hydra:readable' => true,
  608. 'hydra:writeable' => false,
  609. ],
  610. ],
  611. ];
  613. return $classes;
  614. }
  616. /**
  617. * Gets a property definition.
  618. *
  619. * @param ApiProperty|PropertyMetadata $propertyMetadata
  620. */
  621. private function getProperty($propertyMetadata, string $propertyName, string $prefixedShortName, string $shortName): array
  622. {
  623. if ($propertyMetadata instanceof PropertyMetadata) {
  624. $iri = $propertyMetadata->getIri();
  625. } else {
  626. if ($iri = $propertyMetadata->getIris()) {
  627. $iri = 1 === \count($iri) ? $iri[0] : $iri;
  628. }
  629. }
  631. if (!isset($iri)) {
  632. $iri = "#$shortName/$propertyName";
  633. }
  635. $propertyData = [
  636. '@id' => $iri,
  637. '@type' => false === $propertyMetadata->isReadableLink() ? 'hydra:Link' : 'rdf:Property',
  638. 'rdfs:label' => $propertyName,
  639. 'domain' => $prefixedShortName,
  640. ];
  642. // TODO: 3.0 support multiple types, default value of types will be [] instead of null
  643. $type = $propertyMetadata instanceof PropertyMetadata ? $propertyMetadata->getType() : $propertyMetadata->getBuiltinTypes()[0] ?? null;
  645. if (null !== $type && !$type->isCollection() && (null !== $className = $type->getClassName()) && $this->resourceClassResolver->isResourceClass($className)) {
  646. $propertyData['owl:maxCardinality'] = 1;
  647. }
  649. $property = [
  650. '@type' => 'hydra:SupportedProperty',
  651. 'hydra:property' => $propertyData,
  652. 'hydra:title' => $propertyName,
  653. 'hydra:required' => $propertyMetadata->isRequired(),
  654. 'hydra:readable' => $propertyMetadata->isReadable(),
  655. 'hydra:writeable' => $propertyMetadata->isWritable() || $propertyMetadata->isInitializable(),
  656. ];
  658. if (null !== $range = $this->getRange($propertyMetadata)) {
  659. $property['hydra:property']['range'] = $range;
  660. }
  662. if (null !== $description = $propertyMetadata->getDescription()) {
  663. $property['hydra:description'] = $description;
  664. }
  666. if ($deprecationReason = $propertyMetadata instanceof PropertyMetadata ? $propertyMetadata->getAttribute('deprecation_reason') : $propertyMetadata->getDeprecationReason()) {
  667. $property['owl:deprecated'] = true;
  668. }
  670. return $property;
  671. }
  673. /**
  674. * Computes the documentation.
  675. */
  676. private function computeDoc(Documentation $object, array $classes): array
  677. {
  678. $doc = ['@context' => $this->getContext(), '@id' => $this->urlGenerator->generate('api_doc', ['_format' => self::FORMAT]), '@type' => 'hydra:ApiDocumentation'];
  680. if ('' !== $object->getTitle()) {
  681. $doc['hydra:title'] = $object->getTitle();
  682. }
  684. if ('' !== $object->getDescription()) {
  685. $doc['hydra:description'] = $object->getDescription();
  686. }
  688. $doc['hydra:entrypoint'] = $this->urlGenerator->generate('api_entrypoint');
  689. $doc['hydra:supportedClass'] = $classes;
  691. return $doc;
  692. }
  694. /**
  695. * Builds the JSON-LD context for the API documentation.
  696. */
  697. private function getContext(): array
  698. {
  699. return [
  700. '@vocab' => $this->urlGenerator->generate('api_doc', ['_format' => self::FORMAT], UrlGeneratorInterface::ABS_URL).'#',
  701. 'hydra' => ContextBuilderInterface::HYDRA_NS,
  702. 'rdf' => ContextBuilderInterface::RDF_NS,
  703. 'rdfs' => ContextBuilderInterface::RDFS_NS,
  704. 'xmls' => ContextBuilderInterface::XML_NS,
  705. 'owl' => ContextBuilderInterface::OWL_NS,
  706. 'schema' => ContextBuilderInterface::SCHEMA_ORG_NS,
  707. 'domain' => ['@id' => 'rdfs:domain', '@type' => '@id'],
  708. 'range' => ['@id' => 'rdfs:range', '@type' => '@id'],
  709. 'subClassOf' => ['@id' => 'rdfs:subClassOf', '@type' => '@id'],
  710. 'expects' => ['@id' => 'hydra:expects', '@type' => '@id'],
  711. 'returns' => ['@id' => 'hydra:returns', '@type' => '@id'],
  712. ];
  713. }
  715. public function supportsNormalization($data, $format = null, array $context = []): bool
  716. {
  717. return self::FORMAT === $format && $data instanceof Documentation;
  718. }
  720. public function hasCacheableSupportsMethod(): bool
  721. {
  722. return true;
  723. }
  724. }
  726. class_alias(DocumentationNormalizer::class, \ApiPlatform\Core\Hydra\Serializer\DocumentationNormalizer::class);