vendor/api-platform/core/src/Core/Swagger/Serializer/DocumentationNormalizer.php line 169

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\Core\Swagger\Serializer;
  16. use ApiPlatform\Core\Api\FilterCollection;
  17. use ApiPlatform\Core\Api\FilterLocatorTrait;
  18. use ApiPlatform\Core\Api\FormatsProviderInterface;
  19. use ApiPlatform\Core\Api\IdentifiersExtractorInterface;
  20. use ApiPlatform\Core\Api\OperationAwareFormatsProviderInterface;
  21. use ApiPlatform\Core\Api\OperationMethodResolverInterface;
  22. use ApiPlatform\Core\Api\OperationType;
  23. use ApiPlatform\Core\Api\ResourceClassResolverInterface;
  24. use ApiPlatform\Core\Api\UrlGeneratorInterface;
  25. use ApiPlatform\Core\JsonSchema\SchemaFactory as LegacySchemaFactory;
  26. use ApiPlatform\Core\JsonSchema\SchemaFactoryInterface as LegacySchemaFactoryInterface;
  27. use ApiPlatform\Core\Metadata\Property\Factory\PropertyMetadataFactoryInterface;
  28. use ApiPlatform\Core\Metadata\Property\Factory\PropertyNameCollectionFactoryInterface;
  29. use ApiPlatform\Core\Metadata\Resource\ApiResourceToLegacyResourceMetadataTrait;
  30. use ApiPlatform\Core\Metadata\Resource\Factory\ResourceMetadataFactoryInterface;
  31. use ApiPlatform\Core\Metadata\Resource\ResourceMetadata;
  32. use ApiPlatform\Core\Operation\Factory\SubresourceOperationFactoryInterface;
  33. use ApiPlatform\Documentation\Documentation;
  34. use ApiPlatform\Exception\ResourceClassNotFoundException;
  35. use ApiPlatform\Exception\RuntimeException;
  36. use ApiPlatform\JsonSchema\Schema;
  37. use ApiPlatform\JsonSchema\SchemaFactory;
  38. use ApiPlatform\JsonSchema\SchemaFactoryInterface;
  39. use ApiPlatform\JsonSchema\TypeFactory;
  40. use ApiPlatform\JsonSchema\TypeFactoryInterface;
  41. use ApiPlatform\Metadata\HttpOperation;
  42. use ApiPlatform\Metadata\Resource\Factory\ResourceMetadataCollectionFactoryInterface;
  43. use ApiPlatform\OpenApi\OpenApi;
  44. use ApiPlatform\OpenApi\Serializer\ApiGatewayNormalizer;
  45. use ApiPlatform\PathResolver\OperationPathResolverInterface;
  46. use Psr\Container\ContainerInterface;
  47. use Symfony\Component\PropertyInfo\Type;
  48. use Symfony\Component\Serializer\NameConverter\NameConverterInterface;
  49. use Symfony\Component\Serializer\Normalizer\CacheableSupportsMethodInterface;
  50. use Symfony\Component\Serializer\Normalizer\NormalizerInterface;
  52. /**
  53.  * Generates an OpenAPI specification (formerly known as Swagger). OpenAPI v2 and v3 are supported.
  54.  *
  55.  * @author Amrouche Hamza <hamza.simperfit@gmail.com>
  56.  * @author Teoh Han Hui <teohhanhui@gmail.com>
  57.  * @author Kévin Dunglas <dunglas@gmail.com>
  58.  * @author Anthony GRASSIOT <antograssiot@free.fr>
  59.  */
  60. final class DocumentationNormalizer implements NormalizerInterface, CacheableSupportsMethodInterface
  61. {
  62.     use ApiResourceToLegacyResourceMetadataTrait;
  63.     use FilterLocatorTrait;
  65.     public const FORMAT = 'json';
  66.     public const BASE_URL = 'base_url';
  67.     public const SPEC_VERSION = 'spec_version';
  68.     public const OPENAPI_VERSION = '3.0.2';
  69.     public const SWAGGER_DEFINITION_NAME = 'swagger_definition_name';
  70.     public const SWAGGER_VERSION = '2.0';
  72.     /**
  73.      * @deprecated
  74.      */
  75.     public const ATTRIBUTE_NAME = 'swagger_context';
  77.     private $resourceMetadataFactory;
  78.     private $propertyNameCollectionFactory;
  79.     private $propertyMetadataFactory;
  80.     private $operationMethodResolver;
  81.     private $operationPathResolver;
  82.     private $oauthEnabled;
  83.     private $oauthType;
  84.     private $oauthFlow;
  85.     private $oauthTokenUrl;
  86.     private $oauthAuthorizationUrl;
  87.     private $oauthScopes;
  88.     private $apiKeys;
  89.     private $subresourceOperationFactory;
  90.     private $paginationEnabled;
  91.     private $paginationPageParameterName;
  92.     private $clientItemsPerPage;
  93.     private $itemsPerPageParameterName;
  94.     private $paginationClientEnabled;
  95.     private $paginationClientEnabledParameterName;
  96.     private $formats;
  97.     private $formatsProvider;
  99.     /**
  100.      * @var SchemaFactoryInterface|LegacySchemaFactoryInterface
  101.      */
  102.     private $jsonSchemaFactory;
  103.     /**
  104.      * @var TypeFactoryInterface
  105.      */
  106.     private $jsonSchemaTypeFactory;
  107.     private $defaultContext = [
  108.         self::BASE_URL => '/',
  109.         ApiGatewayNormalizer::API_GATEWAY => false,
  110.     ];
  112.     private $identifiersExtractor;
  114.     private $openApiNormalizer;
  115.     private $legacyMode;
  117.     /**
  118.      * @param LegacySchemaFactoryInterface|SchemaFactoryInterface|ResourceClassResolverInterface|null $jsonSchemaFactory
  119.      * @param ContainerInterface|FilterCollection|null                                                $filterLocator
  120.      * @param array|OperationAwareFormatsProviderInterface                                            $formats
  121.      * @param mixed|null                                                                              $jsonSchemaTypeFactory
  122.      * @param int[]                                                                                   $swaggerVersions
  123.      */
  124.     public function __construct($resourceMetadataFactory, PropertyNameCollectionFactoryInterface $propertyNameCollectionFactory, PropertyMetadataFactoryInterface $propertyMetadataFactory, $jsonSchemaFactory = null, $jsonSchemaTypeFactory = null, OperationPathResolverInterface $operationPathResolver = null, UrlGeneratorInterface $urlGenerator = null, $filterLocator = null, NameConverterInterface $nameConverter = null, bool $oauthEnabled = false, string $oauthType = '', string $oauthFlow = '', string $oauthTokenUrl = '', string $oauthAuthorizationUrl = '', array $oauthScopes = [], array $apiKeys = [], SubresourceOperationFactoryInterface $subresourceOperationFactory = null, bool $paginationEnabled = true, string $paginationPageParameterName = 'page', bool $clientItemsPerPage = false, string $itemsPerPageParameterName = 'itemsPerPage', $formats = [], bool $paginationClientEnabled = false, string $paginationClientEnabledParameterName = 'pagination', array $defaultContext = [], array $swaggerVersions = [2, 3], IdentifiersExtractorInterface $identifiersExtractor = null, NormalizerInterface $openApiNormalizer = null, bool $legacyMode = false)
  125.     {
  126.         if ($jsonSchemaTypeFactory instanceof OperationMethodResolverInterface) {
  127.             @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);
  129.             $this->operationMethodResolver = $jsonSchemaTypeFactory;
  130.             $this->jsonSchemaTypeFactory = new TypeFactory();
  131.         } else {
  132.             $this->jsonSchemaTypeFactory = $jsonSchemaTypeFactory ?? new TypeFactory();
  133.         }
  135.         if ($jsonSchemaFactory instanceof ResourceClassResolverInterface) {
  136.             @trigger_error(sprintf('Passing an instance of %s to %s() is deprecated since version 2.5 and will be removed in 3.0.', ResourceClassResolverInterface::class, __METHOD__), \E_USER_DEPRECATED);
  137.         }
  139.         if (null === $jsonSchemaFactory || $jsonSchemaFactory instanceof ResourceClassResolverInterface) {
  140.             if ($resourceMetadataFactory instanceof ResourceMetadataFactoryInterface) {
  141.                 $jsonSchemaFactory = new LegacySchemaFactory($this->jsonSchemaTypeFactory, $resourceMetadataFactory, $propertyNameCollectionFactory, $propertyMetadataFactory, $nameConverter);
  142.             } else {
  143.                 $jsonSchemaFactory = new SchemaFactory($this->jsonSchemaTypeFactory, $resourceMetadataFactory, $propertyNameCollectionFactory, $propertyMetadataFactory, $nameConverter);
  144.             }
  146.             $this->jsonSchemaTypeFactory->setSchemaFactory($jsonSchemaFactory);
  147.         }
  148.         $this->jsonSchemaFactory = $jsonSchemaFactory;
  150.         if ($nameConverter) {
  151.             @trigger_error(sprintf('Passing an instance of %s to %s() is deprecated since version 2.5 and will be removed in 3.0.', NameConverterInterface::class, __METHOD__), \E_USER_DEPRECATED);
  152.         }
  154.         if ($urlGenerator) {
  155.             @trigger_error(sprintf('Passing an instance of %s to %s() is deprecated since version 2.1 and will be removed in 3.0.', UrlGeneratorInterface::class, __METHOD__), \E_USER_DEPRECATED);
  156.         }
  158.         if ($formats instanceof FormatsProviderInterface) {
  159.             @trigger_error(sprintf('Passing an instance of %s to %s() is deprecated since version 2.5 and will be removed in 3.0, pass an array instead.', FormatsProviderInterface::class, __METHOD__), \E_USER_DEPRECATED);
  161.             $this->formatsProvider = $formats;
  162.         } else {
  163.             $this->formats = $formats;
  164.         }
  166.         $this->setFilterLocator($filterLocator, true);
  168.         if ($resourceMetadataFactory instanceof ResourceMetadataFactoryInterface) {
  169.             trigger_deprecation('api-platform/core', '2.7', sprintf('Use "%s" instead of "%s".', ResourceMetadataCollectionFactoryInterface::class, ResourceMetadataFactoryInterface::class));
  170.         }
  172.         $this->resourceMetadataFactory = $resourceMetadataFactory;
  173.         $this->propertyNameCollectionFactory = $propertyNameCollectionFactory;
  174.         $this->propertyMetadataFactory = $propertyMetadataFactory;
  175.         $this->operationPathResolver = $operationPathResolver;
  176.         $this->oauthEnabled = $oauthEnabled;
  177.         $this->oauthType = $oauthType;
  178.         $this->oauthFlow = $oauthFlow;
  179.         $this->oauthTokenUrl = $oauthTokenUrl;
  180.         $this->oauthAuthorizationUrl = $oauthAuthorizationUrl;
  181.         $this->oauthScopes = $oauthScopes;
  182.         $this->subresourceOperationFactory = $subresourceOperationFactory;
  183.         $this->paginationEnabled = $paginationEnabled;
  184.         $this->paginationPageParameterName = $paginationPageParameterName;
  185.         $this->apiKeys = $apiKeys;
  186.         $this->clientItemsPerPage = $clientItemsPerPage;
  187.         $this->itemsPerPageParameterName = $itemsPerPageParameterName;
  188.         $this->paginationClientEnabled = $paginationClientEnabled;
  189.         $this->paginationClientEnabledParameterName = $paginationClientEnabledParameterName;
  190.         $this->defaultContext[self::SPEC_VERSION] = $swaggerVersions[0] ?? 2;
  191.         $this->defaultContext = array_merge($this->defaultContext, $defaultContext);
  192.         $this->identifiersExtractor = $identifiersExtractor;
  193.         $this->openApiNormalizer = $openApiNormalizer;
  194.         $this->legacyMode = $legacyMode;
  195.     }
  197.     /**
  198.      * @param mixed|null $format
  199.      *
  200.      * @return array|string|int|float|bool|\ArrayObject|null
  201.      */
  202.     public function normalize($object, $format = null, array $context = [])
  203.     {
  204.         if ($object instanceof OpenApi) {
  205.             @trigger_error('Using the swagger DocumentationNormalizer is deprecated in favor of decorating the OpenApiFactory, use the "openapi.backward_compatibility_layer" configuration to change this behavior.', \E_USER_DEPRECATED);
  207.             return $this->openApiNormalizer->normalize($object, $format, $context);
  208.         }
  210.         $v3 = 3 === ($context['spec_version'] ?? $this->defaultContext['spec_version']) && !($context['api_gateway'] ?? $this->defaultContext['api_gateway']);
  212.         $definitions = new \ArrayObject();
  213.         $paths = new \ArrayObject();
  214.         $links = new \ArrayObject();
  216.         if ($this->resourceMetadataFactory instanceof ResourceMetadataCollectionFactoryInterface) {
  217.             foreach ($object->getResourceNameCollection() as $resourceClass) {
  218.                 $resourceMetadataCollection = $this->resourceMetadataFactory->create($resourceClass);
  219.                 foreach ($resourceMetadataCollection as $i => $resourceMetadata) {
  220.                     $resourceMetadata = $this->transformResourceToResourceMetadata($resourceMetadata);
  221.                     // Items needs to be parsed first to be able to reference the lines from the collection operation
  222.                     $this->addPaths($v3, $paths, $definitions, $resourceClass, $resourceMetadata->getShortName(), $resourceMetadata, OperationType::ITEM, $links);
  223.                     $this->addPaths($v3, $paths, $definitions, $resourceClass, $resourceMetadata->getShortName(), $resourceMetadata, OperationType::COLLECTION, $links);
  224.                 }
  225.             }
  227.             $definitions->ksort();
  228.             $paths->ksort();
  230.             return $this->computeDoc($v3, $object, $definitions, $paths, $context);
  231.         }
  233.         foreach ($object->getResourceNameCollection() as $resourceClass) {
  234.             $resourceMetadata = $this->resourceMetadataFactory->create($resourceClass);
  236.             if ($this->identifiersExtractor) {
  237.                 $identifiers = [];
  238.                 if ($resourceMetadata->getItemOperations()) {
  239.                     $identifiers = $this->identifiersExtractor->getIdentifiersFromResourceClass($resourceClass);
  240.                 }
  242.                 $resourceMetadata = $resourceMetadata->withAttributes(($resourceMetadata->getAttributes() ?: []) + ['identifiers' => $identifiers]);
  243.             }
  244.             $resourceShortName = $resourceMetadata->getShortName();
  246.             // Items needs to be parsed first to be able to reference the lines from the collection operation
  247.             $this->addPaths($v3, $paths, $definitions, $resourceClass, $resourceShortName, $resourceMetadata, OperationType::ITEM, $links);
  248.             $this->addPaths($v3, $paths, $definitions, $resourceClass, $resourceShortName, $resourceMetadata, OperationType::COLLECTION, $links);
  250.             if (null === $this->subresourceOperationFactory) {
  251.                 continue;
  252.             }
  254.             foreach ($this->subresourceOperationFactory->create($resourceClass) as $operationId => $subresourceOperation) {
  255.                 $method = $resourceMetadata->getTypedOperationAttribute(OperationType::SUBRESOURCE, $subresourceOperation['operation_name'], 'method', 'GET');
  256.                 $paths[$this->getPath($subresourceOperation['shortNames'][0], $subresourceOperation['route_name'], $subresourceOperation, OperationType::SUBRESOURCE)][strtolower($method)] = $this->addSubresourceOperation($v3, $subresourceOperation, $definitions, $operationId, $resourceMetadata);
  257.             }
  258.         }
  260.         $definitions->ksort();
  261.         $paths->ksort();
  263.         return $this->computeDoc($v3, $object, $definitions, $paths, $context);
  264.     }
  266.     /**
  267.      * Updates the list of entries in the paths collection.
  268.      */
  269.     private function addPaths(bool $v3, \ArrayObject $paths, \ArrayObject $definitions, string $resourceClass, string $resourceShortName, ResourceMetadata $resourceMetadata, string $operationType, \ArrayObject $links)
  270.     {
  271.         if (null === $operations = OperationType::COLLECTION === $operationType ? $resourceMetadata->getCollectionOperations() : $resourceMetadata->getItemOperations()) {
  272.             return;
  273.         }
  275.         foreach ($operations as $operationName => $operation) {
  276.             if (false === ($operation['openapi'] ?? null)) {
  277.                 continue;
  278.             }
  280.             // Skolem IRI
  281.             if ('api_genid' === ($operation['route_name'] ?? null)) {
  282.                 continue;
  283.             }
  285.             if (isset($operation['uri_template'])) {
  286.                 $path = str_replace('.{_format}', '', $operation['uri_template']);
  287.                 if (!str_starts_with($path, '/')) {
  288.                     $path = '/'.$path;
  289.                 }
  290.             } else {
  291.                 $path = $this->getPath($resourceShortName, $operationName, $operation, $operationType);
  292.             }
  294.             if ($this->operationMethodResolver) {
  295.                 $method = OperationType::ITEM === $operationType ? $this->operationMethodResolver->getItemOperationMethod($resourceClass, $operationName) : $this->operationMethodResolver->getCollectionOperationMethod($resourceClass, $operationName);
  296.             } else {
  297.                 $method = $resourceMetadata->getTypedOperationAttribute($operationType, $operationName, 'method', 'GET');
  298.             }
  300.             $paths[$path][strtolower($method)] = $this->getPathOperation($v3, $operationName, $operation, $method, $operationType, $resourceClass, $resourceMetadata, $definitions, $links);
  301.         }
  302.     }
  304.     /**
  305.      * Gets the path for an operation.
  306.      *
  307.      * If the path ends with the optional _format parameter, it is removed
  308.      * as optional path parameters are not yet supported.
  309.      *
  310.      * @see https://github.com/OAI/OpenAPI-Specification/issues/93
  311.      */
  312.     private function getPath(string $resourceShortName, string $operationName, array $operation, string $operationType): string
  313.     {
  314.         $path = $this->operationPathResolver->resolveOperationPath($resourceShortName, $operation, $operationType, $operationName);
  316.         if ('.{_format}' === substr($path, -10)) {
  317.             $path = substr($path, 0, -10);
  318.         }
  320.         return $path;
  321.     }
  323.     /**
  324.      * Gets a path Operation Object.
  325.      *
  326.      * @see https://github.com/OAI/OpenAPI-Specification/blob/master/versions/2.0.md#operation-object
  327.      */
  328.     private function getPathOperation(bool $v3, string $operationName, array $operation, string $method, string $operationType, string $resourceClass, ResourceMetadata $resourceMetadata, \ArrayObject $definitions, \ArrayObject $links): \ArrayObject
  329.     {
  330.         $pathOperation = new \ArrayObject($operation[$v3 ? 'openapi_context' : 'swagger_context'] ?? []);
  331.         $resourceShortName = $resourceMetadata->getShortName();
  332.         $pathOperation['tags'] ?? $pathOperation['tags'] = [$resourceShortName];
  333.         $pathOperation['operationId'] ?? $pathOperation['operationId'] = lcfirst($operationName).ucfirst($resourceShortName).ucfirst($operationType);
  334.         if ($v3 && 'GET' === $method && OperationType::ITEM === $operationType && $link = $this->getLinkObject($resourceClass, $pathOperation['operationId'], $this->getPath($resourceShortName, $operationName, $operation, $operationType))) {
  335.             $links[$pathOperation['operationId']] = $link;
  336.         }
  337.         if ($resourceMetadata->getTypedOperationAttribute($operationType, $operationName, 'deprecation_reason', null, true)) {
  338.             $pathOperation['deprecated'] = true;
  339.         }
  341.         if (null === $this->formatsProvider) {
  342.             $requestFormats = $resourceMetadata->getTypedOperationAttribute($operationType, $operationName, 'input_formats', [], true);
  343.             $responseFormats = $resourceMetadata->getTypedOperationAttribute($operationType, $operationName, 'output_formats', [], true);
  344.         } else {
  345.             $requestFormats = $responseFormats = $this->formatsProvider->getFormatsFromOperation($resourceClass, $operationName, $operationType);
  346.         }
  348.         $requestMimeTypes = $this->flattenMimeTypes($requestFormats);
  349.         $responseMimeTypes = $this->flattenMimeTypes($responseFormats);
  350.         switch ($method) {
  351.             case 'GET':
  352.                 return $this->updateGetOperation($v3, $pathOperation, $responseMimeTypes, $operationType, $resourceMetadata, $resourceClass, $resourceShortName, $operationName, $definitions);
  353.             case 'POST':
  354.                 return $this->updatePostOperation($v3, $pathOperation, $requestMimeTypes, $responseMimeTypes, $operationType, $resourceMetadata, $resourceClass, $resourceShortName, $operationName, $definitions, $links);
  355.             case 'PATCH':
  356.                 $pathOperation['summary'] ?? $pathOperation['summary'] = sprintf('Updates the %s resource.', $resourceShortName);
  357.                 // no break
  358.             case 'PUT':
  359.                 return $this->updatePutOperation($v3, $pathOperation, $requestMimeTypes, $responseMimeTypes, $operationType, $resourceMetadata, $resourceClass, $resourceShortName, $operationName, $definitions);
  360.             case 'DELETE':
  361.                 return $this->updateDeleteOperation($v3, $pathOperation, $resourceShortName, $operationType, $operationName, $resourceMetadata, $resourceClass);
  362.         }
  364.         return $pathOperation;
  365.     }
  367.     /**
  368.      * @return array the update message as first value, and if the schema is defined as second
  369.      */
  370.     private function addSchemas(bool $v3, array $message, \ArrayObject $definitions, string $resourceClass, string $operationType, string $operationName, array $mimeTypes, string $type = Schema::TYPE_OUTPUT, bool $forceCollection = false): array
  371.     {
  372.         if (!$v3) {
  373.             $jsonSchema = $this->getJsonSchema($v3, $definitions, $resourceClass, $type, $operationType, $operationName, 'json', null, $forceCollection);
  374.             if (!$jsonSchema->isDefined()) {
  375.                 return [$message, false];
  376.             }
  378.             $message['schema'] = $jsonSchema->getArrayCopy(false);
  380.             return [$message, true];
  381.         }
  383.         foreach ($mimeTypes as $mimeType => $format) {
  384.             $jsonSchema = $this->getJsonSchema($v3, $definitions, $resourceClass, $type, $operationType, $operationName, $format, null, $forceCollection);
  385.             if (!$jsonSchema->isDefined()) {
  386.                 return [$message, false];
  387.             }
  389.             $message['content'][$mimeType] = ['schema' => $jsonSchema->getArrayCopy(false)];
  390.         }
  392.         return [$message, true];
  393.     }
  395.     private function updateGetOperation(bool $v3, \ArrayObject $pathOperation, array $mimeTypes, string $operationType, ResourceMetadata $resourceMetadata, string $resourceClass, string $resourceShortName, string $operationName, \ArrayObject $definitions): \ArrayObject
  396.     {
  397.         $successStatus = (string) $resourceMetadata->getTypedOperationAttribute($operationType, $operationName, 'status', '200');
  399.         if (!$v3) {
  400.             $pathOperation['produces'] ?? $pathOperation['produces'] = array_keys($mimeTypes);
  401.         }
  403.         if (OperationType::COLLECTION === $operationType) {
  404.             $outputResourseShortName = $resourceMetadata->getCollectionOperations()[$operationName]['output']['name'] ?? $resourceShortName;
  405.             $pathOperation['summary'] ?? $pathOperation['summary'] = sprintf('Retrieves the collection of %s resources.', $outputResourseShortName);
  407.             $successResponse = ['description' => sprintf('%s collection response', $outputResourseShortName)];
  408.             [$successResponse] = $this->addSchemas($v3, $successResponse, $definitions, $resourceClass, $operationType, $operationName, $mimeTypes);
  410.             $pathOperation['responses'] ?? $pathOperation['responses'] = [$successStatus => $successResponse];
  412.             if (
  413.                 ($resourceMetadata->getAttributes()['extra_properties']['is_legacy_subresource'] ?? false)
  414.                 || ($resourceMetadata->getAttributes()['extra_properties']['is_alternate_resource_metadata'] ?? false)) {
  415.                 // Avoid duplicates parameters when there is a filter on a subresource identifier
  416.                 $parametersMemory = [];
  417.                 $pathOperation['parameters'] = [];
  419.                 foreach ($resourceMetadata->getCollectionOperations()[$operationName]['identifiers'] as $parameterName => [$class, $identifier]) {
  420.                     $parameter = ['name' => $parameterName, 'in' => 'path', 'required' => true];
  421.                     $v3 ? $parameter['schema'] = ['type' => 'string'] : $parameter['type'] = 'string';
  422.                     $pathOperation['parameters'][] = $parameter;
  423.                     $parametersMemory[] = $parameterName;
  424.                 }
  426.                 if ($parameters = $this->getFiltersParameters($v3, $resourceClass, $operationName, $resourceMetadata)) {
  427.                     foreach ($parameters as $parameter) {
  428.                         if (!\in_array($parameter['name'], $parametersMemory, true)) {
  429.                             $pathOperation['parameters'][] = $parameter;
  430.                         }
  431.                     }
  432.                 }
  433.             } else {
  434.                 $pathOperation['parameters'] ?? $pathOperation['parameters'] = $this->getFiltersParameters($v3, $resourceClass, $operationName, $resourceMetadata);
  435.             }
  437.             $this->addPaginationParameters($v3, $resourceMetadata, OperationType::COLLECTION, $operationName, $pathOperation);
  439.             return $pathOperation;
  440.         }
  442.         $outputResourseShortName = $resourceMetadata->getItemOperations()[$operationName]['output']['name'] ?? $resourceShortName;
  443.         $pathOperation['summary'] ?? $pathOperation['summary'] = sprintf('Retrieves a %s resource.', $outputResourseShortName);
  445.         $pathOperation = $this->addItemOperationParameters($v3, $pathOperation, $operationType, $operationName, $resourceMetadata, $resourceClass);
  447.         $successResponse = ['description' => sprintf('%s resource response', $outputResourseShortName)];
  448.         [$successResponse] = $this->addSchemas($v3, $successResponse, $definitions, $resourceClass, $operationType, $operationName, $mimeTypes);
  450.         $pathOperation['responses'] ?? $pathOperation['responses'] = [
  451.             $successStatus => $successResponse,
  452.             '404' => ['description' => 'Resource not found'],
  453.         ];
  455.         return $pathOperation;
  456.     }
  458.     private function addPaginationParameters(bool $v3, ResourceMetadata $resourceMetadata, string $operationType, string $operationName, \ArrayObject $pathOperation)
  459.     {
  460.         if ($this->paginationEnabled && $resourceMetadata->getTypedOperationAttribute($operationType, $operationName, 'pagination_enabled', true, true)) {
  461.             $paginationParameter = [
  462.                 'name' => $this->paginationPageParameterName,
  463.                 'in' => 'query',
  464.                 'required' => false,
  465.                 'description' => 'The collection page number',
  466.             ];
  467.             $v3 ? $paginationParameter['schema'] = [
  468.                 'type' => 'integer',
  469.                 'default' => 1,
  470.             ] : $paginationParameter['type'] = 'integer';
  471.             $pathOperation['parameters'][] = $paginationParameter;
  473.             if ($resourceMetadata->getTypedOperationAttribute($operationType, $operationName, 'pagination_client_items_per_page', $this->clientItemsPerPage, true)) {
  474.                 $itemPerPageParameter = [
  475.                     'name' => $this->itemsPerPageParameterName,
  476.                     'in' => 'query',
  477.                     'required' => false,
  478.                     'description' => 'The number of items per page',
  479.                 ];
  480.                 if ($v3) {
  481.                     $itemPerPageParameter['schema'] = [
  482.                         'type' => 'integer',
  483.                         'default' => $resourceMetadata->getTypedOperationAttribute($operationType, $operationName, 'pagination_items_per_page', 30, true),
  484.                         'minimum' => 0,
  485.                     ];
  487.                     $maxItemsPerPage = $resourceMetadata->getTypedOperationAttribute($operationType, $operationName, 'maximum_items_per_page', null, true);
  488.                     if (null !== $maxItemsPerPage) {
  489.                         @trigger_error('The "maximum_items_per_page" option has been deprecated since API Platform 2.5 in favor of "pagination_maximum_items_per_page" and will be removed in API Platform 3.', \E_USER_DEPRECATED);
  490.                     }
  491.                     $maxItemsPerPage = $resourceMetadata->getTypedOperationAttribute($operationType, $operationName, 'pagination_maximum_items_per_page', $maxItemsPerPage, true);
  493.                     if (null !== $maxItemsPerPage) {
  494.                         $itemPerPageParameter['schema']['maximum'] = $maxItemsPerPage;
  495.                     }
  496.                 } else {
  497.                     $itemPerPageParameter['type'] = 'integer';
  498.                 }
  500.                 $pathOperation['parameters'][] = $itemPerPageParameter;
  501.             }
  502.         }
  504.         if ($this->paginationEnabled && $resourceMetadata->getTypedOperationAttribute($operationType, $operationName, 'pagination_client_enabled', $this->paginationClientEnabled, true)) {
  505.             $paginationEnabledParameter = [
  506.                 'name' => $this->paginationClientEnabledParameterName,
  507.                 'in' => 'query',
  508.                 'required' => false,
  509.                 'description' => 'Enable or disable pagination',
  510.             ];
  511.             $v3 ? $paginationEnabledParameter['schema'] = ['type' => 'boolean'] : $paginationEnabledParameter['type'] = 'boolean';
  512.             $pathOperation['parameters'][] = $paginationEnabledParameter;
  513.         }
  514.     }
  516.     /**
  517.      * @throws ResourceClassNotFoundException
  518.      */
  519.     private function addSubresourceOperation(bool $v3, array $subresourceOperation, \ArrayObject $definitions, string $operationId, ResourceMetadata $resourceMetadata): \ArrayObject
  520.     {
  521.         $operationName = 'get'; // TODO: we might want to extract that at some point to also support other subresource operations
  522.         $collection = $subresourceOperation['collection'] ?? false;
  524.         $subResourceMetadata = $this->resourceMetadataFactory->create($subresourceOperation['resource_class']);
  526.         $pathOperation = new \ArrayObject([]);
  527.         $pathOperation['tags'] = $subresourceOperation['shortNames'];
  528.         $pathOperation['operationId'] = $operationId;
  529.         $pathOperation['summary'] = sprintf('Retrieves %s%s resource%s.', $subresourceOperation['collection'] ? 'the collection of ' : 'a ', $subresourceOperation['shortNames'][0], $subresourceOperation['collection'] ? 's' : '');
  531.         if (null === $this->formatsProvider) {
  532.             // TODO: Subresource operation metadata aren't available by default, for now we have to fallback on default formats.
  533.             // TODO: A better approach would be to always populate the subresource operation array.
  534.             $subResourceMetadata = $this
  535.                 ->resourceMetadataFactory
  536.                 ->create($subresourceOperation['resource_class']);
  538.             if ($this->resourceMetadataFactory instanceof ResourceMetadataCollectionFactoryInterface) {
  539.                 $subResourceMetadata = $this->transformResourceToResourceMetadata($subResourceMetadata[0]);
  540.             }
  542.             $responseFormats = $subResourceMetadata->getTypedOperationAttribute(OperationType::SUBRESOURCE, $operationName, 'output_formats', $this->formats, true);
  543.         } else {
  544.             $responseFormats = $this->formatsProvider->getFormatsFromOperation($subresourceOperation['resource_class'], $operationName, OperationType::SUBRESOURCE);
  545.         }
  547.         $mimeTypes = $this->flattenMimeTypes($responseFormats);
  549.         if (!$v3) {
  550.             $pathOperation['produces'] = array_keys($mimeTypes);
  551.         }
  553.         $successResponse = [
  554.             'description' => sprintf('%s %s response', $subresourceOperation['shortNames'][0], $collection ? 'collection' : 'resource'),
  555.         ];
  556.         [$successResponse] = $this->addSchemas($v3, $successResponse, $definitions, $subresourceOperation['resource_class'], OperationType::SUBRESOURCE, $operationName, $mimeTypes, Schema::TYPE_OUTPUT, $collection);
  558.         $pathOperation['responses'] = ['200' => $successResponse, '404' => ['description' => 'Resource not found']];
  560.         // Avoid duplicates parameters when there is a filter on a subresource identifier
  561.         $parametersMemory = [];
  562.         $pathOperation['parameters'] = [];
  563.         foreach ($subresourceOperation['identifiers'] as $parameterName => [$class, $identifier, $hasIdentifier]) {
  564.             if (!str_contains($subresourceOperation['path'], sprintf('{%s}', $parameterName))) {
  565.                 continue;
  566.             }
  568.             $parameter = ['name' => $parameterName, 'in' => 'path', 'required' => true];
  569.             $v3 ? $parameter['schema'] = ['type' => 'string'] : $parameter['type'] = 'string';
  570.             $pathOperation['parameters'][] = $parameter;
  571.             $parametersMemory[] = $parameterName;
  572.         }
  574.         if ($parameters = $this->getFiltersParameters($v3, $subresourceOperation['resource_class'], $operationName, $subResourceMetadata)) {
  575.             foreach ($parameters as $parameter) {
  576.                 if (!\in_array($parameter['name'], $parametersMemory, true)) {
  577.                     $pathOperation['parameters'][] = $parameter;
  578.                 }
  579.             }
  580.         }
  582.         if ($subresourceOperation['collection']) {
  583.             $this->addPaginationParameters($v3, $subResourceMetadata, OperationType::SUBRESOURCE, $subresourceOperation['operation_name'], $pathOperation);
  584.         }
  586.         return $pathOperation;
  587.     }
  589.     private function updatePostOperation(bool $v3, \ArrayObject $pathOperation, array $requestMimeTypes, array $responseMimeTypes, string $operationType, ResourceMetadata $resourceMetadata, string $resourceClass, string $resourceShortName, string $operationName, \ArrayObject $definitions, \ArrayObject $links): \ArrayObject
  590.     {
  591.         if (!$v3) {
  592.             $pathOperation['consumes'] ?? $pathOperation['consumes'] = array_keys($requestMimeTypes);
  593.             $pathOperation['produces'] ?? $pathOperation['produces'] = array_keys($responseMimeTypes);
  594.         }
  596.         $pathOperation['summary'] ?? $pathOperation['summary'] = sprintf('Creates a %s resource.', $resourceShortName);
  598.         $identifiers = (array) $resourceMetadata
  599.                 ->getTypedOperationAttribute($operationType, $operationName, 'identifiers', [], false);
  601.         $pathOperation = $this->addItemOperationParameters($v3, $pathOperation, $operationType, $operationName, $resourceMetadata, $resourceClass, OperationType::ITEM === $operationType ? false : true);
  603.         $successResponse = ['description' => sprintf('%s resource created', $resourceShortName)];
  604.         [$successResponse, $defined] = $this->addSchemas($v3, $successResponse, $definitions, $resourceClass, $operationType, $operationName, $responseMimeTypes);
  606.         if ($defined && $v3 && ($links[$key = 'get'.ucfirst($resourceShortName).ucfirst(OperationType::ITEM)] ?? null)) {
  607.             $successResponse['links'] = [ucfirst($key) => $links[$key]];
  608.         }
  610.         $pathOperation['responses'] ?? $pathOperation['responses'] = [
  611.             (string) $resourceMetadata->getTypedOperationAttribute($operationType, $operationName, 'status', '201') => $successResponse,
  612.             '400' => ['description' => 'Invalid input'],
  613.             '404' => ['description' => 'Resource not found'],
  614.             '422' => ['description' => 'Unprocessable entity'],
  615.         ];
  617.         return $this->addRequestBody($v3, $pathOperation, $definitions, $resourceClass, $resourceShortName, $operationType, $operationName, $requestMimeTypes);
  618.     }
  620.     private function updatePutOperation(bool $v3, \ArrayObject $pathOperation, array $requestMimeTypes, array $responseMimeTypes, string $operationType, ResourceMetadata $resourceMetadata, string $resourceClass, string $resourceShortName, string $operationName, \ArrayObject $definitions): \ArrayObject
  621.     {
  622.         if (!$v3) {
  623.             $pathOperation['consumes'] ?? $pathOperation['consumes'] = array_keys($requestMimeTypes);
  624.             $pathOperation['produces'] ?? $pathOperation['produces'] = array_keys($responseMimeTypes);
  625.         }
  627.         $pathOperation['summary'] ?? $pathOperation['summary'] = sprintf('Replaces the %s resource.', $resourceShortName);
  629.         $pathOperation = $this->addItemOperationParameters($v3, $pathOperation, $operationType, $operationName, $resourceMetadata, $resourceClass);
  631.         $successResponse = ['description' => sprintf('%s resource updated', $resourceShortName)];
  632.         [$successResponse] = $this->addSchemas($v3, $successResponse, $definitions, $resourceClass, $operationType, $operationName, $responseMimeTypes);
  634.         $pathOperation['responses'] ?? $pathOperation['responses'] = [
  635.             (string) $resourceMetadata->getTypedOperationAttribute($operationType, $operationName, 'status', '200') => $successResponse,
  636.             '400' => ['description' => 'Invalid input'],
  637.             '404' => ['description' => 'Resource not found'],
  638.             '422' => ['description' => 'Unprocessable entity'],
  639.         ];
  641.         return $this->addRequestBody($v3, $pathOperation, $definitions, $resourceClass, $resourceShortName, $operationType, $operationName, $requestMimeTypes, true);
  642.     }
  644.     private function addRequestBody(bool $v3, \ArrayObject $pathOperation, \ArrayObject $definitions, string $resourceClass, string $resourceShortName, string $operationType, string $operationName, array $requestMimeTypes, bool $put = false)
  645.     {
  646.         if (isset($pathOperation['requestBody'])) {
  647.             return $pathOperation;
  648.         }
  650.         [$message, $defined] = $this->addSchemas($v3, [], $definitions, $resourceClass, $operationType, $operationName, $requestMimeTypes, Schema::TYPE_INPUT);
  651.         if (!$defined) {
  652.             return $pathOperation;
  653.         }
  655.         $description = sprintf('The %s %s resource', $put ? 'updated' : 'new', $resourceShortName);
  656.         if ($v3) {
  657.             $pathOperation['requestBody'] = $message + ['description' => $description];
  659.             return $pathOperation;
  660.         }
  662.         if (!$this->hasBodyParameter($pathOperation['parameters'] ?? [])) {
  663.             $pathOperation['parameters'][] = [
  664.                 'name' => lcfirst($resourceShortName),
  665.                 'in' => 'body',
  666.                 'description' => $description,
  667.             ] + $message;
  668.         }
  670.         return $pathOperation;
  671.     }
  673.     private function hasBodyParameter(array $parameters): bool
  674.     {
  675.         foreach ($parameters as $parameter) {
  676.             if (\array_key_exists('in', $parameter) && 'body' === $parameter['in']) {
  677.                 return true;
  678.             }
  679.         }
  681.         return false;
  682.     }
  684.     private function updateDeleteOperation(bool $v3, \ArrayObject $pathOperation, string $resourceShortName, string $operationType, string $operationName, ResourceMetadata $resourceMetadata, string $resourceClass): \ArrayObject
  685.     {
  686.         $pathOperation['summary'] ?? $pathOperation['summary'] = sprintf('Removes the %s resource.', $resourceShortName);
  687.         $pathOperation['responses'] ?? $pathOperation['responses'] = [
  688.             (string) $resourceMetadata->getTypedOperationAttribute($operationType, $operationName, 'status', '204') => ['description' => sprintf('%s resource deleted', $resourceShortName)],
  689.             '404' => ['description' => 'Resource not found'],
  690.         ];
  692.         return $this->addItemOperationParameters($v3, $pathOperation, $operationType, $operationName, $resourceMetadata, $resourceClass);
  693.     }
  695.     private function addItemOperationParameters(bool $v3, \ArrayObject $pathOperation, string $operationType, string $operationName, ResourceMetadata $resourceMetadata, string $resourceClass, bool $isPost = false): \ArrayObject
  696.     {
  697.         $identifiers = (array) $resourceMetadata
  698.                 ->getTypedOperationAttribute($operationType, $operationName, 'identifiers', [], false);
  700.         // Auto-generated routes in API Platform < 2.7 are considered as collection, hotfix this as the OpenApi Factory supports new operations anyways.
  701.         // this also fixes a bug where we could not create POST item operations in API P 2.6
  702.         if (OperationType::ITEM === $operationType && $isPost) {
  703.             $operationType = OperationType::COLLECTION;
  704.         }
  706.         if (!$identifiers && OperationType::COLLECTION !== $operationType) {
  707.             try {
  708.                 $identifiers = $this->identifiersExtractor->getIdentifiersFromResourceClass($resourceClass);
  709.             } catch (RuntimeException $e) {
  710.                 // Ignore exception here
  711.             } catch (ResourceClassNotFoundException $e) {
  712.                 if (false === $this->legacyMode) {
  713.                     // Skipping these, swagger is not compatible with post 2.7 resource metadata
  714.                     return $pathOperation;
  715.                 }
  716.                 throw $e;
  717.             }
  718.         }
  720.         if (\count($identifiers) > 1 ? $resourceMetadata->getItemOperationAttribute($operationName, 'composite_identifier', true, true) : false) {
  721.             $identifiers = ['id'];
  722.         }
  724.         if (!$identifiers && OperationType::COLLECTION === $operationType) {
  725.             return $pathOperation;
  726.         }
  728.         if (!isset($pathOperation['parameters'])) {
  729.             $pathOperation['parameters'] = [];
  730.         }
  732.         foreach ($identifiers as $parameterName => $identifier) {
  733.             $parameter = [
  734.                 'name' => \is_string($parameterName) ? $parameterName : $identifier,
  735.                 'in' => 'path',
  736.                 'required' => true,
  737.             ];
  738.             $v3 ? $parameter['schema'] = ['type' => 'string'] : $parameter['type'] = 'string';
  739.             $pathOperation['parameters'][] = $parameter;
  740.         }
  742.         return $pathOperation;
  743.     }
  745.     private function getJsonSchema(bool $v3, \ArrayObject $definitions, string $resourceClass, string $type, ?string $operationType, ?string $operationName, string $format = 'json', array $serializerContext = null, bool $forceCollection = false): Schema
  746.     {
  747.         $schema = new Schema($v3 ? Schema::VERSION_OPENAPI : Schema::VERSION_SWAGGER);
  748.         $schema->setDefinitions($definitions);
  750.         if ($this->jsonSchemaFactory instanceof SchemaFactoryInterface) {
  751.             $operation = $operationName ? (new class() extends HttpOperation {})->withName($operationName) : null;
  753.             return $this->jsonSchemaFactory->buildSchema($resourceClass, $format, $type, $operation, $schema, $serializerContext, $forceCollection);
  754.         }
  756.         return $this->jsonSchemaFactory->buildSchema($resourceClass, $format, $type, $operationType, $operationName, $schema, $serializerContext, $forceCollection);
  757.     }
  759.     private function computeDoc(bool $v3, Documentation $documentation, \ArrayObject $definitions, \ArrayObject $paths, array $context): array
  760.     {
  761.         $baseUrl = $context[self::BASE_URL] ?? $this->defaultContext[self::BASE_URL];
  763.         if ($v3) {
  764.             $docs = ['openapi' => self::OPENAPI_VERSION];
  765.             if ('/' !== $baseUrl && '' !== $baseUrl) {
  766.                 $docs['servers'] = [['url' => $baseUrl]];
  767.             }
  768.         } else {
  769.             $docs = [
  770.                 'swagger' => self::SWAGGER_VERSION,
  771.                 'basePath' => $baseUrl,
  772.             ];
  773.         }
  775.         $docs += [
  776.             'info' => [
  777.                 'title' => $documentation->getTitle(),
  778.                 'version' => $documentation->getVersion(),
  779.             ],
  780.             'paths' => $paths,
  781.         ];
  783.         if ('' !== $description = $documentation->getDescription()) {
  784.             $docs['info']['description'] = $description;
  785.         }
  787.         $securityDefinitions = [];
  788.         $security = [];
  790.         if ($this->oauthEnabled) {
  791.             $oauthAttributes = [
  792.                 'authorizationUrl' => $this->oauthAuthorizationUrl,
  793.                 'scopes' => new \ArrayObject($this->oauthScopes),
  794.             ];
  796.             if ($this->oauthTokenUrl) {
  797.                 $oauthAttributes['tokenUrl'] = $this->oauthTokenUrl;
  798.             }
  800.             $securityDefinitions['oauth'] = [
  801.                 'type' => $this->oauthType,
  802.                 'description' => sprintf(
  803.                     'OAuth 2.0 %s Grant',
  804.                     strtolower(preg_replace('/[A-Z]/', ' \\0', lcfirst($this->oauthFlow)))
  805.                 ),
  806.             ];
  808.             if ($v3) {
  809.                 $securityDefinitions['oauth']['flows'] = [
  810.                     $this->oauthFlow => $oauthAttributes,
  811.                 ];
  812.             } else {
  813.                 $securityDefinitions['oauth']['flow'] = $this->oauthFlow;
  814.                 $securityDefinitions['oauth'] = array_merge($securityDefinitions['oauth'], $oauthAttributes);
  815.             }
  817.             $security[] = ['oauth' => []];
  818.         }
  820.         foreach ($this->apiKeys as $key => $apiKey) {
  821.             $name = $apiKey['name'];
  822.             $type = $apiKey['type'];
  824.             $securityDefinitions[$key] = [
  825.                 'type' => 'apiKey',
  826.                 'in' => $type,
  827.                 'description' => sprintf('Value for the %s %s', $name, 'query' === $type ? sprintf('%s parameter', $type) : $type),
  828.                 'name' => $name,
  829.             ];
  831.             $security[] = [$key => []];
  832.         }
  834.         if ($securityDefinitions && $security) { // @phpstan-ignore-line false positive
  835.             $docs['security'] = $security;
  836.             if (!$v3) {
  837.                 $docs['securityDefinitions'] = $securityDefinitions;
  838.             }
  839.         }
  841.         if ($v3) {
  842.             if (\count($definitions) + \count($securityDefinitions)) {
  843.                 $docs['components'] = [];
  844.                 if (\count($definitions)) {
  845.                     $docs['components']['schemas'] = $definitions;
  846.                 }
  847.                 if (\count($securityDefinitions)) {
  848.                     $docs['components']['securitySchemes'] = $securityDefinitions;
  849.                 }
  850.             }
  851.         } elseif (\count($definitions) > 0) {
  852.             $docs['definitions'] = $definitions;
  853.         }
  855.         return $docs;
  856.     }
  858.     /**
  859.      * Gets parameters corresponding to enabled filters.
  860.      */
  861.     private function getFiltersParameters(bool $v3, string $resourceClass, string $operationName, ResourceMetadata $resourceMetadata): array
  862.     {
  863.         if (null === $this->filterLocator) {
  864.             return [];
  865.         }
  867.         $parameters = [];
  868.         $resourceFilters = $resourceMetadata->getCollectionOperationAttribute($operationName, 'filters', [], true);
  869.         foreach ($resourceFilters as $filterId) {
  870.             if (!$filter = $this->getFilter($filterId)) {
  871.                 continue;
  872.             }
  874.             foreach ($filter->getDescription($resourceClass) as $name => $data) {
  875.                 $parameter = [
  876.                     'name' => $name,
  877.                     'in' => 'query',
  878.                     'required' => $data['required'],
  879.                 ];
  881.                 $type = \in_array($data['type'], Type::$builtinTypes, true) ? $this->jsonSchemaTypeFactory->getType(new Type($data['type'], false, null, $data['is_collection'] ?? false)) : ['type' => 'string'];
  882.                 $v3 ? $parameter['schema'] = $type : $parameter += $type;
  884.                 if ($v3 && isset($data['schema'])) {
  885.                     $parameter['schema'] = $data['schema'];
  886.                 }
  888.                 if ('array' === ($type['type'] ?? '')) {
  889.                     $deepObject = \in_array($data['type'], [Type::BUILTIN_TYPE_ARRAY, Type::BUILTIN_TYPE_OBJECT], true);
  891.                     if ($v3) {
  892.                         $parameter['style'] = $deepObject ? 'deepObject' : 'form';
  893.                         $parameter['explode'] = true;
  894.                     } else {
  895.                         $parameter['collectionFormat'] = $deepObject ? 'csv' : 'multi';
  896.                     }
  897.                 }
  899.                 $key = $v3 ? 'openapi' : 'swagger';
  900.                 if (isset($data[$key])) {
  901.                     $parameter = $data[$key] + $parameter;
  902.                 }
  904.                 $parameters[] = $parameter;
  905.             }
  906.         }
  908.         return $parameters;
  909.     }
  911.     public function supportsNormalization($data, $format = null, array $context = []): bool
  912.     {
  913.         return self::FORMAT === $format && ($data instanceof Documentation || $this->openApiNormalizer && $data instanceof OpenApi);
  914.     }
  916.     public function hasCacheableSupportsMethod(): bool
  917.     {
  918.         return true;
  919.     }
  921.     private function flattenMimeTypes(array $responseFormats): array
  922.     {
  923.         $responseMimeTypes = [];
  924.         foreach ($responseFormats as $responseFormat => $mimeTypes) {
  925.             foreach ($mimeTypes as $mimeType) {
  926.                 $responseMimeTypes[$mimeType] = $responseFormat;
  927.             }
  928.         }
  930.         return $responseMimeTypes;
  931.     }
  933.     /**
  934.      * https://github.com/OAI/OpenAPI-Specification/blob/master/versions/3.0.0.md#linkObject.
  935.      */
  936.     private function getLinkObject(string $resourceClass, string $operationId, string $path): array
  937.     {
  938.         $linkObject = $identifiers = [];
  939.         foreach ($this->propertyNameCollectionFactory->create($resourceClass) as $propertyName) {
  940.             $propertyMetadata = $this->propertyMetadataFactory->create($resourceClass, $propertyName);
  941.             if (!$propertyMetadata->isIdentifier()) {
  942.                 continue;
  943.             }
  945.             $linkObject['parameters'][$propertyName] = sprintf('$response.body#/%s', $propertyName);
  946.             $identifiers[] = $propertyName;
  947.         }
  949.         if (!$linkObject) {
  950.             return [];
  951.         }
  952.         $linkObject['operationId'] = $operationId;
  953.         $linkObject['description'] = 1 === \count($identifiers) ? sprintf('The `%1$s` value returned in the response can be used as the `%1$s` parameter in `GET %2$s`.', $identifiers[0], $path) : sprintf('The values returned in the response can be used in `GET %s`.', $path);
  955.         return $linkObject;
  956.     }
  957. }