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

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.      * @param mixed                                                                                   $resourceMetadataFactory
  124.      */
  125.     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)
  126.     {
  127.         if ($jsonSchemaTypeFactory instanceof OperationMethodResolverInterface) {
  128.             @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);
  130.             $this->operationMethodResolver = $jsonSchemaTypeFactory;
  131.             $this->jsonSchemaTypeFactory = new TypeFactory();
  132.         } else {
  133.             $this->jsonSchemaTypeFactory = $jsonSchemaTypeFactory ?? new TypeFactory();
  134.         }
  136.         if ($jsonSchemaFactory instanceof ResourceClassResolverInterface) {
  137.             @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);
  138.         }
  140.         if (null === $jsonSchemaFactory || $jsonSchemaFactory instanceof ResourceClassResolverInterface) {
  141.             if ($resourceMetadataFactory instanceof ResourceMetadataFactoryInterface) {
  142.                 $jsonSchemaFactory = new LegacySchemaFactory($this->jsonSchemaTypeFactory, $resourceMetadataFactory, $propertyNameCollectionFactory, $propertyMetadataFactory, $nameConverter);
  143.             } else {
  144.                 $jsonSchemaFactory = new SchemaFactory($this->jsonSchemaTypeFactory, $resourceMetadataFactory, $propertyNameCollectionFactory, $propertyMetadataFactory, $nameConverter);
  145.             }
  147.             $this->jsonSchemaTypeFactory->setSchemaFactory($jsonSchemaFactory);
  148.         }
  149.         $this->jsonSchemaFactory = $jsonSchemaFactory;
  151.         if ($nameConverter) {
  152.             @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);
  153.         }
  155.         if ($urlGenerator) {
  156.             @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);
  157.         }
  159.         if ($formats instanceof FormatsProviderInterface) {
  160.             @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);
  162.             $this->formatsProvider = $formats;
  163.         } else {
  164.             $this->formats = $formats;
  165.         }
  167.         $this->setFilterLocator($filterLocator, true);
  169.         if ($resourceMetadataFactory instanceof ResourceMetadataFactoryInterface) {
  170.             trigger_deprecation('api-platform/core', '2.7', sprintf('Use "%s" instead of "%s".', ResourceMetadataCollectionFactoryInterface::class, ResourceMetadataFactoryInterface::class));
  171.         }
  173.         $this->resourceMetadataFactory = $resourceMetadataFactory;
  174.         $this->propertyNameCollectionFactory = $propertyNameCollectionFactory;
  175.         $this->propertyMetadataFactory = $propertyMetadataFactory;
  176.         $this->operationPathResolver = $operationPathResolver;
  177.         $this->oauthEnabled = $oauthEnabled;
  178.         $this->oauthType = $oauthType;
  179.         $this->oauthFlow = $oauthFlow;
  180.         $this->oauthTokenUrl = $oauthTokenUrl;
  181.         $this->oauthAuthorizationUrl = $oauthAuthorizationUrl;
  182.         $this->oauthScopes = $oauthScopes;
  183.         $this->subresourceOperationFactory = $subresourceOperationFactory;
  184.         $this->paginationEnabled = $paginationEnabled;
  185.         $this->paginationPageParameterName = $paginationPageParameterName;
  186.         $this->apiKeys = $apiKeys;
  187.         $this->clientItemsPerPage = $clientItemsPerPage;
  188.         $this->itemsPerPageParameterName = $itemsPerPageParameterName;
  189.         $this->paginationClientEnabled = $paginationClientEnabled;
  190.         $this->paginationClientEnabledParameterName = $paginationClientEnabledParameterName;
  191.         $this->defaultContext[self::SPEC_VERSION] = $swaggerVersions[0] ?? 2;
  192.         $this->defaultContext = array_merge($this->defaultContext, $defaultContext);
  193.         $this->identifiersExtractor = $identifiersExtractor;
  194.         $this->openApiNormalizer = $openApiNormalizer;
  195.         $this->legacyMode = $legacyMode;
  196.     }
  198.     /**
  199.      * {@inheritdoc}
  200.      *
  201.      * @return array|string|int|float|bool|\ArrayObject|null
  202.      */
  203.     public function normalize($object, $format = null, array $context = [])
  204.     {
  205.         if ($object instanceof OpenApi) {
  206.             @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);
  208.             return $this->openApiNormalizer->normalize($object, $format, $context);
  209.         }
  211.         $v3 = 3 === ($context['spec_version'] ?? $this->defaultContext['spec_version']) && !($context['api_gateway'] ?? $this->defaultContext['api_gateway']);
  213.         $definitions = new \ArrayObject();
  214.         $paths = new \ArrayObject();
  215.         $links = new \ArrayObject();
  217.         if ($this->resourceMetadataFactory instanceof ResourceMetadataCollectionFactoryInterface) {
  218.             foreach ($object->getResourceNameCollection() as $resourceClass) {
  219.                 $resourceMetadataCollection = $this->resourceMetadataFactory->create($resourceClass);
  220.                 foreach ($resourceMetadataCollection as $i => $resourceMetadata) {
  221.                     $resourceMetadata = $this->transformResourceToResourceMetadata($resourceMetadata);
  222.                     // Items needs to be parsed first to be able to reference the lines from the collection operation
  223.                     $this->addPaths($v3, $paths, $definitions, $resourceClass, $resourceMetadata->getShortName(), $resourceMetadata, OperationType::ITEM, $links);
  224.                     $this->addPaths($v3, $paths, $definitions, $resourceClass, $resourceMetadata->getShortName(), $resourceMetadata, OperationType::COLLECTION, $links);
  225.                 }
  226.             }
  228.             $definitions->ksort();
  229.             $paths->ksort();
  231.             return $this->computeDoc($v3, $object, $definitions, $paths, $context);
  232.         }
  234.         foreach ($object->getResourceNameCollection() as $resourceClass) {
  235.             $resourceMetadata = $this->resourceMetadataFactory->create($resourceClass);
  237.             if ($this->identifiersExtractor) {
  238.                 $identifiers = [];
  239.                 if ($resourceMetadata->getItemOperations()) {
  240.                     $identifiers = $this->identifiersExtractor->getIdentifiersFromResourceClass($resourceClass);
  241.                 }
  243.                 $resourceMetadata = $resourceMetadata->withAttributes(($resourceMetadata->getAttributes() ?: []) + ['identifiers' => $identifiers]);
  244.             }
  245.             $resourceShortName = $resourceMetadata->getShortName();
  247.             // Items needs to be parsed first to be able to reference the lines from the collection operation
  248.             $this->addPaths($v3, $paths, $definitions, $resourceClass, $resourceShortName, $resourceMetadata, OperationType::ITEM, $links);
  249.             $this->addPaths($v3, $paths, $definitions, $resourceClass, $resourceShortName, $resourceMetadata, OperationType::COLLECTION, $links);
  251.             if (null === $this->subresourceOperationFactory) {
  252.                 continue;
  253.             }
  255.             foreach ($this->subresourceOperationFactory->create($resourceClass) as $operationId => $subresourceOperation) {
  256.                 $method = $resourceMetadata->getTypedOperationAttribute(OperationType::SUBRESOURCE, $subresourceOperation['operation_name'], 'method', 'GET');
  257.                 $paths[$this->getPath($subresourceOperation['shortNames'][0], $subresourceOperation['route_name'], $subresourceOperation, OperationType::SUBRESOURCE)][strtolower($method)] = $this->addSubresourceOperation($v3, $subresourceOperation, $definitions, $operationId, $resourceMetadata);
  258.             }
  259.         }
  261.         $definitions->ksort();
  262.         $paths->ksort();
  264.         return $this->computeDoc($v3, $object, $definitions, $paths, $context);
  265.     }
  267.     /**
  268.      * Updates the list of entries in the paths collection.
  269.      */
  270.     private function addPaths(bool $v3, \ArrayObject $paths, \ArrayObject $definitions, string $resourceClass, string $resourceShortName, ResourceMetadata $resourceMetadata, string $operationType, \ArrayObject $links)
  271.     {
  272.         if (null === $operations = OperationType::COLLECTION === $operationType ? $resourceMetadata->getCollectionOperations() : $resourceMetadata->getItemOperations()) {
  273.             return;
  274.         }
  276.         foreach ($operations as $operationName => $operation) {
  277.             // Skolem IRI
  278.             if ('api_genid' === ($operation['route_name'] ?? null)) {
  279.                 continue;
  280.             }
  282.             if (isset($operation['uri_template'])) {
  283.                 $path = str_replace('.{_format}', '', $operation['uri_template']);
  284.                 if (0 !== strpos($path, '/')) {
  285.                     $path = '/'.$path;
  286.                 }
  287.             } else {
  288.                 $path = $this->getPath($resourceShortName, $operationName, $operation, $operationType);
  289.             }
  291.             if ($this->operationMethodResolver) {
  292.                 $method = OperationType::ITEM === $operationType ? $this->operationMethodResolver->getItemOperationMethod($resourceClass, $operationName) : $this->operationMethodResolver->getCollectionOperationMethod($resourceClass, $operationName);
  293.             } else {
  294.                 $method = $resourceMetadata->getTypedOperationAttribute($operationType, $operationName, 'method', 'GET');
  295.             }
  297.             $paths[$path][strtolower($method)] = $this->getPathOperation($v3, $operationName, $operation, $method, $operationType, $resourceClass, $resourceMetadata, $definitions, $links);
  298.         }
  299.     }
  301.     /**
  302.      * Gets the path for an operation.
  303.      *
  304.      * If the path ends with the optional _format parameter, it is removed
  305.      * as optional path parameters are not yet supported.
  306.      *
  307.      * @see https://github.com/OAI/OpenAPI-Specification/issues/93
  308.      */
  309.     private function getPath(string $resourceShortName, string $operationName, array $operation, string $operationType): string
  310.     {
  311.         $path = $this->operationPathResolver->resolveOperationPath($resourceShortName, $operation, $operationType, $operationName);
  313.         if ('.{_format}' === substr($path, -10)) {
  314.             $path = substr($path, 0, -10);
  315.         }
  317.         return $path;
  318.     }
  320.     /**
  321.      * Gets a path Operation Object.
  322.      *
  323.      * @see https://github.com/OAI/OpenAPI-Specification/blob/master/versions/2.0.md#operation-object
  324.      */
  325.     private function getPathOperation(bool $v3, string $operationName, array $operation, string $method, string $operationType, string $resourceClass, ResourceMetadata $resourceMetadata, \ArrayObject $definitions, \ArrayObject $links): \ArrayObject
  326.     {
  327.         $pathOperation = new \ArrayObject($operation[$v3 ? 'openapi_context' : 'swagger_context'] ?? []);
  328.         $resourceShortName = $resourceMetadata->getShortName();
  329.         $pathOperation['tags'] ?? $pathOperation['tags'] = [$resourceShortName];
  330.         $pathOperation['operationId'] ?? $pathOperation['operationId'] = lcfirst($operationName).ucfirst($resourceShortName).ucfirst($operationType);
  331.         if ($v3 && 'GET' === $method && OperationType::ITEM === $operationType && $link = $this->getLinkObject($resourceClass, $pathOperation['operationId'], $this->getPath($resourceShortName, $operationName, $operation, $operationType))) {
  332.             $links[$pathOperation['operationId']] = $link;
  333.         }
  334.         if ($resourceMetadata->getTypedOperationAttribute($operationType, $operationName, 'deprecation_reason', null, true)) {
  335.             $pathOperation['deprecated'] = true;
  336.         }
  338.         if (null === $this->formatsProvider) {
  339.             $requestFormats = $resourceMetadata->getTypedOperationAttribute($operationType, $operationName, 'input_formats', [], true);
  340.             $responseFormats = $resourceMetadata->getTypedOperationAttribute($operationType, $operationName, 'output_formats', [], true);
  341.         } else {
  342.             $requestFormats = $responseFormats = $this->formatsProvider->getFormatsFromOperation($resourceClass, $operationName, $operationType);
  343.         }
  345.         $requestMimeTypes = $this->flattenMimeTypes($requestFormats);
  346.         $responseMimeTypes = $this->flattenMimeTypes($responseFormats);
  347.         switch ($method) {
  348.             case 'GET':
  349.                 return $this->updateGetOperation($v3, $pathOperation, $responseMimeTypes, $operationType, $resourceMetadata, $resourceClass, $resourceShortName, $operationName, $definitions);
  350.             case 'POST':
  351.                 return $this->updatePostOperation($v3, $pathOperation, $requestMimeTypes, $responseMimeTypes, $operationType, $resourceMetadata, $resourceClass, $resourceShortName, $operationName, $definitions, $links);
  352.             case 'PATCH':
  353.                 $pathOperation['summary'] ?? $pathOperation['summary'] = sprintf('Updates the %s resource.', $resourceShortName);
  354.                 // no break
  355.             case 'PUT':
  356.                 return $this->updatePutOperation($v3, $pathOperation, $requestMimeTypes, $responseMimeTypes, $operationType, $resourceMetadata, $resourceClass, $resourceShortName, $operationName, $definitions);
  357.             case 'DELETE':
  358.                 return $this->updateDeleteOperation($v3, $pathOperation, $resourceShortName, $operationType, $operationName, $resourceMetadata, $resourceClass);
  359.         }
  361.         return $pathOperation;
  362.     }
  364.     /**
  365.      * @return array the update message as first value, and if the schema is defined as second
  366.      */
  367.     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
  368.     {
  369.         if (!$v3) {
  370.             $jsonSchema = $this->getJsonSchema($v3, $definitions, $resourceClass, $type, $operationType, $operationName, 'json', null, $forceCollection);
  371.             if (!$jsonSchema->isDefined()) {
  372.                 return [$message, false];
  373.             }
  375.             $message['schema'] = $jsonSchema->getArrayCopy(false);
  377.             return [$message, true];
  378.         }
  380.         foreach ($mimeTypes as $mimeType => $format) {
  381.             $jsonSchema = $this->getJsonSchema($v3, $definitions, $resourceClass, $type, $operationType, $operationName, $format, null, $forceCollection);
  382.             if (!$jsonSchema->isDefined()) {
  383.                 return [$message, false];
  384.             }
  386.             $message['content'][$mimeType] = ['schema' => $jsonSchema->getArrayCopy(false)];
  387.         }
  389.         return [$message, true];
  390.     }
  392.     private function updateGetOperation(bool $v3, \ArrayObject $pathOperation, array $mimeTypes, string $operationType, ResourceMetadata $resourceMetadata, string $resourceClass, string $resourceShortName, string $operationName, \ArrayObject $definitions): \ArrayObject
  393.     {
  394.         $successStatus = (string) $resourceMetadata->getTypedOperationAttribute($operationType, $operationName, 'status', '200');
  396.         if (!$v3) {
  397.             $pathOperation['produces'] ?? $pathOperation['produces'] = array_keys($mimeTypes);
  398.         }
  400.         if (OperationType::COLLECTION === $operationType) {
  401.             $outputResourseShortName = $resourceMetadata->getCollectionOperations()[$operationName]['output']['name'] ?? $resourceShortName;
  402.             $pathOperation['summary'] ?? $pathOperation['summary'] = sprintf('Retrieves the collection of %s resources.', $outputResourseShortName);
  404.             $successResponse = ['description' => sprintf('%s collection response', $outputResourseShortName)];
  405.             [$successResponse] = $this->addSchemas($v3, $successResponse, $definitions, $resourceClass, $operationType, $operationName, $mimeTypes);
  407.             $pathOperation['responses'] ?? $pathOperation['responses'] = [$successStatus => $successResponse];
  409.             if (
  410.                 ($resourceMetadata->getAttributes()['extra_properties']['is_legacy_subresource'] ?? false) ||
  411.                 ($resourceMetadata->getAttributes()['extra_properties']['is_alternate_resource_metadata'] ?? false)) {
  412.                 // Avoid duplicates parameters when there is a filter on a subresource identifier
  413.                 $parametersMemory = [];
  414.                 $pathOperation['parameters'] = [];
  416.                 foreach ($resourceMetadata->getCollectionOperations()[$operationName]['identifiers'] as $parameterName => [$class, $identifier]) {
  417.                     $parameter = ['name' => $parameterName, 'in' => 'path', 'required' => true];
  418.                     $v3 ? $parameter['schema'] = ['type' => 'string'] : $parameter['type'] = 'string';
  419.                     $pathOperation['parameters'][] = $parameter;
  420.                     $parametersMemory[] = $parameterName;
  421.                 }
  423.                 if ($parameters = $this->getFiltersParameters($v3, $resourceClass, $operationName, $resourceMetadata)) {
  424.                     foreach ($parameters as $parameter) {
  425.                         if (!\in_array($parameter['name'], $parametersMemory, true)) {
  426.                             $pathOperation['parameters'][] = $parameter;
  427.                         }
  428.                     }
  429.                 }
  430.             } else {
  431.                 $pathOperation['parameters'] ?? $pathOperation['parameters'] = $this->getFiltersParameters($v3, $resourceClass, $operationName, $resourceMetadata);
  432.             }
  434.             $this->addPaginationParameters($v3, $resourceMetadata, OperationType::COLLECTION, $operationName, $pathOperation);
  436.             return $pathOperation;
  437.         }
  439.         $outputResourseShortName = $resourceMetadata->getItemOperations()[$operationName]['output']['name'] ?? $resourceShortName;
  440.         $pathOperation['summary'] ?? $pathOperation['summary'] = sprintf('Retrieves a %s resource.', $outputResourseShortName);
  442.         $pathOperation = $this->addItemOperationParameters($v3, $pathOperation, $operationType, $operationName, $resourceMetadata, $resourceClass);
  444.         $successResponse = ['description' => sprintf('%s resource response', $outputResourseShortName)];
  445.         [$successResponse] = $this->addSchemas($v3, $successResponse, $definitions, $resourceClass, $operationType, $operationName, $mimeTypes);
  447.         $pathOperation['responses'] ?? $pathOperation['responses'] = [
  448.             $successStatus => $successResponse,
  449.             '404' => ['description' => 'Resource not found'],
  450.         ];
  452.         return $pathOperation;
  453.     }
  455.     private function addPaginationParameters(bool $v3, ResourceMetadata $resourceMetadata, string $operationType, string $operationName, \ArrayObject $pathOperation)
  456.     {
  457.         if ($this->paginationEnabled && $resourceMetadata->getTypedOperationAttribute($operationType, $operationName, 'pagination_enabled', true, true)) {
  458.             $paginationParameter = [
  459.                 'name' => $this->paginationPageParameterName,
  460.                 'in' => 'query',
  461.                 'required' => false,
  462.                 'description' => 'The collection page number',
  463.             ];
  464.             $v3 ? $paginationParameter['schema'] = [
  465.                 'type' => 'integer',
  466.                 'default' => 1,
  467.             ] : $paginationParameter['type'] = 'integer';
  468.             $pathOperation['parameters'][] = $paginationParameter;
  470.             if ($resourceMetadata->getTypedOperationAttribute($operationType, $operationName, 'pagination_client_items_per_page', $this->clientItemsPerPage, true)) {
  471.                 $itemPerPageParameter = [
  472.                     'name' => $this->itemsPerPageParameterName,
  473.                     'in' => 'query',
  474.                     'required' => false,
  475.                     'description' => 'The number of items per page',
  476.                 ];
  477.                 if ($v3) {
  478.                     $itemPerPageParameter['schema'] = [
  479.                         'type' => 'integer',
  480.                         'default' => $resourceMetadata->getTypedOperationAttribute($operationType, $operationName, 'pagination_items_per_page', 30, true),
  481.                         'minimum' => 0,
  482.                     ];
  484.                     $maxItemsPerPage = $resourceMetadata->getTypedOperationAttribute($operationType, $operationName, 'maximum_items_per_page', null, true);
  485.                     if (null !== $maxItemsPerPage) {
  486.                         @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);
  487.                     }
  488.                     $maxItemsPerPage = $resourceMetadata->getTypedOperationAttribute($operationType, $operationName, 'pagination_maximum_items_per_page', $maxItemsPerPage, true);
  490.                     if (null !== $maxItemsPerPage) {
  491.                         $itemPerPageParameter['schema']['maximum'] = $maxItemsPerPage;
  492.                     }
  493.                 } else {
  494.                     $itemPerPageParameter['type'] = 'integer';
  495.                 }
  497.                 $pathOperation['parameters'][] = $itemPerPageParameter;
  498.             }
  499.         }
  501.         if ($this->paginationEnabled && $resourceMetadata->getTypedOperationAttribute($operationType, $operationName, 'pagination_client_enabled', $this->paginationClientEnabled, true)) {
  502.             $paginationEnabledParameter = [
  503.                 'name' => $this->paginationClientEnabledParameterName,
  504.                 'in' => 'query',
  505.                 'required' => false,
  506.                 'description' => 'Enable or disable pagination',
  507.             ];
  508.             $v3 ? $paginationEnabledParameter['schema'] = ['type' => 'boolean'] : $paginationEnabledParameter['type'] = 'boolean';
  509.             $pathOperation['parameters'][] = $paginationEnabledParameter;
  510.         }
  511.     }
  513.     /**
  514.      * @throws ResourceClassNotFoundException
  515.      */
  516.     private function addSubresourceOperation(bool $v3, array $subresourceOperation, \ArrayObject $definitions, string $operationId, ResourceMetadata $resourceMetadata): \ArrayObject
  517.     {
  518.         $operationName = 'get'; // TODO: we might want to extract that at some point to also support other subresource operations
  519.         $collection = $subresourceOperation['collection'] ?? false;
  521.         $subResourceMetadata = $this->resourceMetadataFactory->create($subresourceOperation['resource_class']);
  523.         $pathOperation = new \ArrayObject([]);
  524.         $pathOperation['tags'] = $subresourceOperation['shortNames'];
  525.         $pathOperation['operationId'] = $operationId;
  526.         $pathOperation['summary'] = sprintf('Retrieves %s%s resource%s.', $subresourceOperation['collection'] ? 'the collection of ' : 'a ', $subresourceOperation['shortNames'][0], $subresourceOperation['collection'] ? 's' : '');
  528.         if (null === $this->formatsProvider) {
  529.             // TODO: Subresource operation metadata aren't available by default, for now we have to fallback on default formats.
  530.             // TODO: A better approach would be to always populate the subresource operation array.
  531.             $subResourceMetadata = $this
  532.                 ->resourceMetadataFactory
  533.                 ->create($subresourceOperation['resource_class']);
  535.             if ($this->resourceMetadataFactory instanceof ResourceMetadataCollectionFactoryInterface) {
  536.                 $subResourceMetadata = $this->transformResourceToResourceMetadata($subResourceMetadata[0]);
  537.             }
  539.             $responseFormats = $subResourceMetadata->getTypedOperationAttribute(OperationType::SUBRESOURCE, $operationName, 'output_formats', $this->formats, true);
  540.         } else {
  541.             $responseFormats = $this->formatsProvider->getFormatsFromOperation($subresourceOperation['resource_class'], $operationName, OperationType::SUBRESOURCE);
  542.         }
  544.         $mimeTypes = $this->flattenMimeTypes($responseFormats);
  546.         if (!$v3) {
  547.             $pathOperation['produces'] = array_keys($mimeTypes);
  548.         }
  550.         $successResponse = [
  551.             'description' => sprintf('%s %s response', $subresourceOperation['shortNames'][0], $collection ? 'collection' : 'resource'),
  552.         ];
  553.         [$successResponse] = $this->addSchemas($v3, $successResponse, $definitions, $subresourceOperation['resource_class'], OperationType::SUBRESOURCE, $operationName, $mimeTypes, Schema::TYPE_OUTPUT, $collection);
  555.         $pathOperation['responses'] = ['200' => $successResponse, '404' => ['description' => 'Resource not found']];
  557.         // Avoid duplicates parameters when there is a filter on a subresource identifier
  558.         $parametersMemory = [];
  559.         $pathOperation['parameters'] = [];
  560.         foreach ($subresourceOperation['identifiers'] as $parameterName => [$class, $identifier, $hasIdentifier]) {
  561.             if (false === strpos($subresourceOperation['path'], sprintf('{%s}', $parameterName))) {
  562.                 continue;
  563.             }
  565.             $parameter = ['name' => $parameterName, 'in' => 'path', 'required' => true];
  566.             $v3 ? $parameter['schema'] = ['type' => 'string'] : $parameter['type'] = 'string';
  567.             $pathOperation['parameters'][] = $parameter;
  568.             $parametersMemory[] = $parameterName;
  569.         }
  571.         if ($parameters = $this->getFiltersParameters($v3, $subresourceOperation['resource_class'], $operationName, $subResourceMetadata)) {
  572.             foreach ($parameters as $parameter) {
  573.                 if (!\in_array($parameter['name'], $parametersMemory, true)) {
  574.                     $pathOperation['parameters'][] = $parameter;
  575.                 }
  576.             }
  577.         }
  579.         if ($subresourceOperation['collection']) {
  580.             $this->addPaginationParameters($v3, $subResourceMetadata, OperationType::SUBRESOURCE, $subresourceOperation['operation_name'], $pathOperation);
  581.         }
  583.         return $pathOperation;
  584.     }
  586.     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
  587.     {
  588.         if (!$v3) {
  589.             $pathOperation['consumes'] ?? $pathOperation['consumes'] = array_keys($requestMimeTypes);
  590.             $pathOperation['produces'] ?? $pathOperation['produces'] = array_keys($responseMimeTypes);
  591.         }
  593.         $pathOperation['summary'] ?? $pathOperation['summary'] = sprintf('Creates a %s resource.', $resourceShortName);
  595.         $identifiers = (array) $resourceMetadata
  596.                 ->getTypedOperationAttribute($operationType, $operationName, 'identifiers', [], false);
  598.         $pathOperation = $this->addItemOperationParameters($v3, $pathOperation, $operationType, $operationName, $resourceMetadata, $resourceClass, OperationType::ITEM === $operationType ? false : true);
  600.         $successResponse = ['description' => sprintf('%s resource created', $resourceShortName)];
  601.         [$successResponse, $defined] = $this->addSchemas($v3, $successResponse, $definitions, $resourceClass, $operationType, $operationName, $responseMimeTypes);
  603.         if ($defined && $v3 && ($links[$key = 'get'.ucfirst($resourceShortName).ucfirst(OperationType::ITEM)] ?? null)) {
  604.             $successResponse['links'] = [ucfirst($key) => $links[$key]];
  605.         }
  607.         $pathOperation['responses'] ?? $pathOperation['responses'] = [
  608.             (string) $resourceMetadata->getTypedOperationAttribute($operationType, $operationName, 'status', '201') => $successResponse,
  609.             '400' => ['description' => 'Invalid input'],
  610.             '404' => ['description' => 'Resource not found'],
  611.             '422' => ['description' => 'Unprocessable entity'],
  612.         ];
  614.         return $this->addRequestBody($v3, $pathOperation, $definitions, $resourceClass, $resourceShortName, $operationType, $operationName, $requestMimeTypes);
  615.     }
  617.     private function updatePutOperation(bool $v3, \ArrayObject $pathOperation, array $requestMimeTypes, array $responseMimeTypes, string $operationType, ResourceMetadata $resourceMetadata, string $resourceClass, string $resourceShortName, string $operationName, \ArrayObject $definitions): \ArrayObject
  618.     {
  619.         if (!$v3) {
  620.             $pathOperation['consumes'] ?? $pathOperation['consumes'] = array_keys($requestMimeTypes);
  621.             $pathOperation['produces'] ?? $pathOperation['produces'] = array_keys($responseMimeTypes);
  622.         }
  624.         $pathOperation['summary'] ?? $pathOperation['summary'] = sprintf('Replaces the %s resource.', $resourceShortName);
  626.         $pathOperation = $this->addItemOperationParameters($v3, $pathOperation, $operationType, $operationName, $resourceMetadata, $resourceClass);
  628.         $successResponse = ['description' => sprintf('%s resource updated', $resourceShortName)];
  629.         [$successResponse] = $this->addSchemas($v3, $successResponse, $definitions, $resourceClass, $operationType, $operationName, $responseMimeTypes);
  631.         $pathOperation['responses'] ?? $pathOperation['responses'] = [
  632.             (string) $resourceMetadata->getTypedOperationAttribute($operationType, $operationName, 'status', '200') => $successResponse,
  633.             '400' => ['description' => 'Invalid input'],
  634.             '404' => ['description' => 'Resource not found'],
  635.             '422' => ['description' => 'Unprocessable entity'],
  636.         ];
  638.         return $this->addRequestBody($v3, $pathOperation, $definitions, $resourceClass, $resourceShortName, $operationType, $operationName, $requestMimeTypes, true);
  639.     }
  641.     private function addRequestBody(bool $v3, \ArrayObject $pathOperation, \ArrayObject $definitions, string $resourceClass, string $resourceShortName, string $operationType, string $operationName, array $requestMimeTypes, bool $put = false)
  642.     {
  643.         if (isset($pathOperation['requestBody'])) {
  644.             return $pathOperation;
  645.         }
  647.         [$message, $defined] = $this->addSchemas($v3, [], $definitions, $resourceClass, $operationType, $operationName, $requestMimeTypes, Schema::TYPE_INPUT);
  648.         if (!$defined) {
  649.             return $pathOperation;
  650.         }
  652.         $description = sprintf('The %s %s resource', $put ? 'updated' : 'new', $resourceShortName);
  653.         if ($v3) {
  654.             $pathOperation['requestBody'] = $message + ['description' => $description];
  656.             return $pathOperation;
  657.         }
  659.         if (!$this->hasBodyParameter($pathOperation['parameters'] ?? [])) {
  660.             $pathOperation['parameters'][] = [
  661.                 'name' => lcfirst($resourceShortName),
  662.                 'in' => 'body',
  663.                 'description' => $description,
  664.             ] + $message;
  665.         }
  667.         return $pathOperation;
  668.     }
  670.     private function hasBodyParameter(array $parameters): bool
  671.     {
  672.         foreach ($parameters as $parameter) {
  673.             if (\array_key_exists('in', $parameter) && 'body' === $parameter['in']) {
  674.                 return true;
  675.             }
  676.         }
  678.         return false;
  679.     }
  681.     private function updateDeleteOperation(bool $v3, \ArrayObject $pathOperation, string $resourceShortName, string $operationType, string $operationName, ResourceMetadata $resourceMetadata, string $resourceClass): \ArrayObject
  682.     {
  683.         $pathOperation['summary'] ?? $pathOperation['summary'] = sprintf('Removes the %s resource.', $resourceShortName);
  684.         $pathOperation['responses'] ?? $pathOperation['responses'] = [
  685.             (string) $resourceMetadata->getTypedOperationAttribute($operationType, $operationName, 'status', '204') => ['description' => sprintf('%s resource deleted', $resourceShortName)],
  686.             '404' => ['description' => 'Resource not found'],
  687.         ];
  689.         return $this->addItemOperationParameters($v3, $pathOperation, $operationType, $operationName, $resourceMetadata, $resourceClass);
  690.     }
  692.     private function addItemOperationParameters(bool $v3, \ArrayObject $pathOperation, string $operationType, string $operationName, ResourceMetadata $resourceMetadata, string $resourceClass, bool $isPost = false): \ArrayObject
  693.     {
  694.         $identifiers = (array) $resourceMetadata
  695.                 ->getTypedOperationAttribute($operationType, $operationName, 'identifiers', [], false);
  697.         // Auto-generated routes in API Platform < 2.7 are considered as collection, hotfix this as the OpenApi Factory supports new operations anyways.
  698.         // this also fixes a bug where we could not create POST item operations in API P 2.6
  699.         if (OperationType::ITEM === $operationType && $isPost) {
  700.             $operationType = OperationType::COLLECTION;
  701.         }
  703.         if (!$identifiers && OperationType::COLLECTION !== $operationType) {
  704.             try {
  705.                 $identifiers = $this->identifiersExtractor->getIdentifiersFromResourceClass($resourceClass);
  706.             } catch (RuntimeException $e) {
  707.                 // Ignore exception here
  708.             } catch (ResourceClassNotFoundException $e) {
  709.                 if (false === $this->legacyMode) {
  710.                     // Skipping these, swagger is not compatible with post 2.7 resource metadata
  711.                     return $pathOperation;
  712.                 }
  713.                 throw $e;
  714.             }
  715.         }
  717.         if (\count($identifiers) > 1 ? $resourceMetadata->getItemOperationAttribute($operationName, 'composite_identifier', true, true) : false) {
  718.             $identifiers = ['id'];
  719.         }
  721.         if (!$identifiers && OperationType::COLLECTION === $operationType) {
  722.             return $pathOperation;
  723.         }
  725.         if (!isset($pathOperation['parameters'])) {
  726.             $pathOperation['parameters'] = [];
  727.         }
  729.         foreach ($identifiers as $parameterName => $identifier) {
  730.             $parameter = [
  731.                 'name' => \is_string($parameterName) ? $parameterName : $identifier,
  732.                 'in' => 'path',
  733.                 'required' => true,
  734.             ];
  735.             $v3 ? $parameter['schema'] = ['type' => 'string'] : $parameter['type'] = 'string';
  736.             $pathOperation['parameters'][] = $parameter;
  737.         }
  739.         return $pathOperation;
  740.     }
  742.     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
  743.     {
  744.         $schema = new Schema($v3 ? Schema::VERSION_OPENAPI : Schema::VERSION_SWAGGER);
  745.         $schema->setDefinitions($definitions);
  747.         if ($this->jsonSchemaFactory instanceof SchemaFactoryInterface) {
  748.             $operation = $operationName ? (new class() extends HttpOperation {})->withName($operationName) : null;
  750.             return $this->jsonSchemaFactory->buildSchema($resourceClass, $format, $type, $operation, $schema, $serializerContext, $forceCollection);
  751.         }
  753.         return $this->jsonSchemaFactory->buildSchema($resourceClass, $format, $type, $operationType, $operationName, $schema, $serializerContext, $forceCollection);
  754.     }
  756.     private function computeDoc(bool $v3, Documentation $documentation, \ArrayObject $definitions, \ArrayObject $paths, array $context): array
  757.     {
  758.         $baseUrl = $context[self::BASE_URL] ?? $this->defaultContext[self::BASE_URL];
  760.         if ($v3) {
  761.             $docs = ['openapi' => self::OPENAPI_VERSION];
  762.             if ('/' !== $baseUrl && '' !== $baseUrl) {
  763.                 $docs['servers'] = [['url' => $baseUrl]];
  764.             }
  765.         } else {
  766.             $docs = [
  767.                 'swagger' => self::SWAGGER_VERSION,
  768.                 'basePath' => $baseUrl,
  769.             ];
  770.         }
  772.         $docs += [
  773.             'info' => [
  774.                 'title' => $documentation->getTitle(),
  775.                 'version' => $documentation->getVersion(),
  776.             ],
  777.             'paths' => $paths,
  778.         ];
  780.         if ('' !== $description = $documentation->getDescription()) {
  781.             $docs['info']['description'] = $description;
  782.         }
  784.         $securityDefinitions = [];
  785.         $security = [];
  787.         if ($this->oauthEnabled) {
  788.             $oauthAttributes = [
  789.                 'authorizationUrl' => $this->oauthAuthorizationUrl,
  790.                 'scopes' => new \ArrayObject($this->oauthScopes),
  791.             ];
  793.             if ($this->oauthTokenUrl) {
  794.                 $oauthAttributes['tokenUrl'] = $this->oauthTokenUrl;
  795.             }
  797.             $securityDefinitions['oauth'] = [
  798.                 'type' => $this->oauthType,
  799.                 'description' => sprintf(
  800.                     'OAuth 2.0 %s Grant',
  801.                     strtolower(preg_replace('/[A-Z]/', ' \\0', lcfirst($this->oauthFlow)))
  802.                 ),
  803.             ];
  805.             if ($v3) {
  806.                 $securityDefinitions['oauth']['flows'] = [
  807.                     $this->oauthFlow => $oauthAttributes,
  808.                 ];
  809.             } else {
  810.                 $securityDefinitions['oauth']['flow'] = $this->oauthFlow;
  811.                 $securityDefinitions['oauth'] = array_merge($securityDefinitions['oauth'], $oauthAttributes);
  812.             }
  814.             $security[] = ['oauth' => []];
  815.         }
  817.         foreach ($this->apiKeys as $key => $apiKey) {
  818.             $name = $apiKey['name'];
  819.             $type = $apiKey['type'];
  821.             $securityDefinitions[$key] = [
  822.                 'type' => 'apiKey',
  823.                 'in' => $type,
  824.                 'description' => sprintf('Value for the %s %s', $name, 'query' === $type ? sprintf('%s parameter', $type) : $type),
  825.                 'name' => $name,
  826.             ];
  828.             $security[] = [$key => []];
  829.         }
  831.         if ($securityDefinitions && $security) { // @phpstan-ignore-line false positive
  832.             $docs['security'] = $security;
  833.             if (!$v3) {
  834.                 $docs['securityDefinitions'] = $securityDefinitions;
  835.             }
  836.         }
  838.         if ($v3) {
  839.             if (\count($definitions) + \count($securityDefinitions)) {
  840.                 $docs['components'] = [];
  841.                 if (\count($definitions)) {
  842.                     $docs['components']['schemas'] = $definitions;
  843.                 }
  844.                 if (\count($securityDefinitions)) {
  845.                     $docs['components']['securitySchemes'] = $securityDefinitions;
  846.                 }
  847.             }
  848.         } elseif (\count($definitions) > 0) {
  849.             $docs['definitions'] = $definitions;
  850.         }
  852.         return $docs;
  853.     }
  855.     /**
  856.      * Gets parameters corresponding to enabled filters.
  857.      */
  858.     private function getFiltersParameters(bool $v3, string $resourceClass, string $operationName, ResourceMetadata $resourceMetadata): array
  859.     {
  860.         if (null === $this->filterLocator) {
  861.             return [];
  862.         }
  864.         $parameters = [];
  865.         $resourceFilters = $resourceMetadata->getCollectionOperationAttribute($operationName, 'filters', [], true);
  866.         foreach ($resourceFilters as $filterId) {
  867.             if (!$filter = $this->getFilter($filterId)) {
  868.                 continue;
  869.             }
  871.             foreach ($filter->getDescription($resourceClass) as $name => $data) {
  872.                 $parameter = [
  873.                     'name' => $name,
  874.                     'in' => 'query',
  875.                     'required' => $data['required'],
  876.                 ];
  878.                 $type = \in_array($data['type'], Type::$builtinTypes, true) ? $this->jsonSchemaTypeFactory->getType(new Type($data['type'], false, null, $data['is_collection'] ?? false)) : ['type' => 'string'];
  879.                 $v3 ? $parameter['schema'] = $type : $parameter += $type;
  881.                 if ($v3 && isset($data['schema'])) {
  882.                     $parameter['schema'] = $data['schema'];
  883.                 }
  885.                 if ('array' === ($type['type'] ?? '')) {
  886.                     $deepObject = \in_array($data['type'], [Type::BUILTIN_TYPE_ARRAY, Type::BUILTIN_TYPE_OBJECT], true);
  888.                     if ($v3) {
  889.                         $parameter['style'] = $deepObject ? 'deepObject' : 'form';
  890.                         $parameter['explode'] = true;
  891.                     } else {
  892.                         $parameter['collectionFormat'] = $deepObject ? 'csv' : 'multi';
  893.                     }
  894.                 }
  896.                 $key = $v3 ? 'openapi' : 'swagger';
  897.                 if (isset($data[$key])) {
  898.                     $parameter = $data[$key] + $parameter;
  899.                 }
  901.                 $parameters[] = $parameter;
  902.             }
  903.         }
  905.         return $parameters;
  906.     }
  908.     /**
  909.      * {@inheritdoc}
  910.      */
  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.     /**
  917.      * {@inheritdoc}
  918.      */
  919.     public function hasCacheableSupportsMethod(): bool
  920.     {
  921.         return true;
  922.     }
  924.     private function flattenMimeTypes(array $responseFormats): array
  925.     {
  926.         $responseMimeTypes = [];
  927.         foreach ($responseFormats as $responseFormat => $mimeTypes) {
  928.             foreach ($mimeTypes as $mimeType) {
  929.                 $responseMimeTypes[$mimeType] = $responseFormat;
  930.             }
  931.         }
  933.         return $responseMimeTypes;
  934.     }
  936.     /**
  937.      * https://github.com/OAI/OpenAPI-Specification/blob/master/versions/3.0.0.md#linkObject.
  938.      */
  939.     private function getLinkObject(string $resourceClass, string $operationId, string $path): array
  940.     {
  941.         $linkObject = $identifiers = [];
  942.         foreach ($this->propertyNameCollectionFactory->create($resourceClass) as $propertyName) {
  943.             $propertyMetadata = $this->propertyMetadataFactory->create($resourceClass, $propertyName);
  944.             if (!$propertyMetadata->isIdentifier()) {
  945.                 continue;
  946.             }
  948.             $linkObject['parameters'][$propertyName] = sprintf('$response.body#/%s', $propertyName);
  949.             $identifiers[] = $propertyName;
  950.         }
  952.         if (!$linkObject) {
  953.             return [];
  954.         }
  955.         $linkObject['operationId'] = $operationId;
  956.         $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);
  958.         return $linkObject;
  959.     }
  960. }