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 <[email protected]>
  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 <[email protected]>
  56.  * @author Teoh Han Hui <[email protected]>
  57.  * @author Kévin Dunglas <[email protected]>
  58.  * @author Anthony GRASSIOT <[email protected]>
  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.             if (false === ($operation['openapi'] ?? null)) {
  278.                 continue;
  279.             }
  281.             // Skolem IRI
  282.             if ('api_genid' === ($operation['route_name'] ?? null)) {
  283.                 continue;
  284.             }
  286.             if (isset($operation['uri_template'])) {
  287.                 $path = str_replace('.{_format}', '', $operation['uri_template']);
  288.                 if (0 !== strpos($path, '/')) {
  289.                     $path = '/'.$path;
  290.                 }
  291.             } else {
  292.                 $path = $this->getPath($resourceShortName, $operationName, $operation, $operationType);
  293.             }
  295.             if ($this->operationMethodResolver) {
  296.                 $method = OperationType::ITEM === $operationType ? $this->operationMethodResolver->getItemOperationMethod($resourceClass, $operationName) : $this->operationMethodResolver->getCollectionOperationMethod($resourceClass, $operationName);
  297.             } else {
  298.                 $method = $resourceMetadata->getTypedOperationAttribute($operationType, $operationName, 'method', 'GET');
  299.             }
  301.             $paths[$path][strtolower($method)] = $this->getPathOperation($v3, $operationName, $operation, $method, $operationType, $resourceClass, $resourceMetadata, $definitions, $links);
  302.         }
  303.     }
  305.     /**
  306.      * Gets the path for an operation.
  307.      *
  308.      * If the path ends with the optional _format parameter, it is removed
  309.      * as optional path parameters are not yet supported.
  310.      *
  311.      * @see https://github.com/OAI/OpenAPI-Specification/issues/93
  312.      */
  313.     private function getPath(string $resourceShortName, string $operationName, array $operation, string $operationType): string
  314.     {
  315.         $path = $this->operationPathResolver->resolveOperationPath($resourceShortName, $operation, $operationType, $operationName);
  317.         if ('.{_format}' === substr($path, -10)) {
  318.             $path = substr($path, 0, -10);
  319.         }
  321.         return $path;
  322.     }
  324.     /**
  325.      * Gets a path Operation Object.
  326.      *
  327.      * @see https://github.com/OAI/OpenAPI-Specification/blob/master/versions/2.0.md#operation-object
  328.      */
  329.     private function getPathOperation(bool $v3, string $operationName, array $operation, string $method, string $operationType, string $resourceClass, ResourceMetadata $resourceMetadata, \ArrayObject $definitions, \ArrayObject $links): \ArrayObject
  330.     {
  331.         $pathOperation = new \ArrayObject($operation[$v3 ? 'openapi_context' : 'swagger_context'] ?? []);
  332.         $resourceShortName = $resourceMetadata->getShortName();
  333.         $pathOperation['tags'] ?? $pathOperation['tags'] = [$resourceShortName];
  334.         $pathOperation['operationId'] ?? $pathOperation['operationId'] = lcfirst($operationName).ucfirst($resourceShortName).ucfirst($operationType);
  335.         if ($v3 && 'GET' === $method && OperationType::ITEM === $operationType && $link = $this->getLinkObject($resourceClass, $pathOperation['operationId'], $this->getPath($resourceShortName, $operationName, $operation, $operationType))) {
  336.             $links[$pathOperation['operationId']] = $link;
  337.         }
  338.         if ($resourceMetadata->getTypedOperationAttribute($operationType, $operationName, 'deprecation_reason', null, true)) {
  339.             $pathOperation['deprecated'] = true;
  340.         }
  342.         if (null === $this->formatsProvider) {
  343.             $requestFormats = $resourceMetadata->getTypedOperationAttribute($operationType, $operationName, 'input_formats', [], true);
  344.             $responseFormats = $resourceMetadata->getTypedOperationAttribute($operationType, $operationName, 'output_formats', [], true);
  345.         } else {
  346.             $requestFormats = $responseFormats = $this->formatsProvider->getFormatsFromOperation($resourceClass, $operationName, $operationType);
  347.         }
  349.         $requestMimeTypes = $this->flattenMimeTypes($requestFormats);
  350.         $responseMimeTypes = $this->flattenMimeTypes($responseFormats);
  351.         switch ($method) {
  352.             case 'GET':
  353.                 return $this->updateGetOperation($v3, $pathOperation, $responseMimeTypes, $operationType, $resourceMetadata, $resourceClass, $resourceShortName, $operationName, $definitions);
  354.             case 'POST':
  355.                 return $this->updatePostOperation($v3, $pathOperation, $requestMimeTypes, $responseMimeTypes, $operationType, $resourceMetadata, $resourceClass, $resourceShortName, $operationName, $definitions, $links);
  356.             case 'PATCH':
  357.                 $pathOperation['summary'] ?? $pathOperation['summary'] = sprintf('Updates the %s resource.', $resourceShortName);
  358.                 // no break
  359.             case 'PUT':
  360.                 return $this->updatePutOperation($v3, $pathOperation, $requestMimeTypes, $responseMimeTypes, $operationType, $resourceMetadata, $resourceClass, $resourceShortName, $operationName, $definitions);
  361.             case 'DELETE':
  362.                 return $this->updateDeleteOperation($v3, $pathOperation, $resourceShortName, $operationType, $operationName, $resourceMetadata, $resourceClass);
  363.         }
  365.         return $pathOperation;
  366.     }
  368.     /**
  369.      * @return array the update message as first value, and if the schema is defined as second
  370.      */
  371.     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
  372.     {
  373.         if (!$v3) {
  374.             $jsonSchema = $this->getJsonSchema($v3, $definitions, $resourceClass, $type, $operationType, $operationName, 'json', null, $forceCollection);
  375.             if (!$jsonSchema->isDefined()) {
  376.                 return [$message, false];
  377.             }
  379.             $message['schema'] = $jsonSchema->getArrayCopy(false);
  381.             return [$message, true];
  382.         }
  384.         foreach ($mimeTypes as $mimeType => $format) {
  385.             $jsonSchema = $this->getJsonSchema($v3, $definitions, $resourceClass, $type, $operationType, $operationName, $format, null, $forceCollection);
  386.             if (!$jsonSchema->isDefined()) {
  387.                 return [$message, false];
  388.             }
  390.             $message['content'][$mimeType] = ['schema' => $jsonSchema->getArrayCopy(false)];
  391.         }
  393.         return [$message, true];
  394.     }
  396.     private function updateGetOperation(bool $v3, \ArrayObject $pathOperation, array $mimeTypes, string $operationType, ResourceMetadata $resourceMetadata, string $resourceClass, string $resourceShortName, string $operationName, \ArrayObject $definitions): \ArrayObject
  397.     {
  398.         $successStatus = (string) $resourceMetadata->getTypedOperationAttribute($operationType, $operationName, 'status', '200');
  400.         if (!$v3) {
  401.             $pathOperation['produces'] ?? $pathOperation['produces'] = array_keys($mimeTypes);
  402.         }
  404.         if (OperationType::COLLECTION === $operationType) {
  405.             $outputResourseShortName = $resourceMetadata->getCollectionOperations()[$operationName]['output']['name'] ?? $resourceShortName;
  406.             $pathOperation['summary'] ?? $pathOperation['summary'] = sprintf('Retrieves the collection of %s resources.', $outputResourseShortName);
  408.             $successResponse = ['description' => sprintf('%s collection response', $outputResourseShortName)];
  409.             [$successResponse] = $this->addSchemas($v3, $successResponse, $definitions, $resourceClass, $operationType, $operationName, $mimeTypes);
  411.             $pathOperation['responses'] ?? $pathOperation['responses'] = [$successStatus => $successResponse];
  413.             if (
  414.                 ($resourceMetadata->getAttributes()['extra_properties']['is_legacy_subresource'] ?? false) ||
  415.                 ($resourceMetadata->getAttributes()['extra_properties']['is_alternate_resource_metadata'] ?? false)) {
  416.                 // Avoid duplicates parameters when there is a filter on a subresource identifier
  417.                 $parametersMemory = [];
  418.                 $pathOperation['parameters'] = [];
  420.                 foreach ($resourceMetadata->getCollectionOperations()[$operationName]['identifiers'] as $parameterName => [$class, $identifier]) {
  421.                     $parameter = ['name' => $parameterName, 'in' => 'path', 'required' => true];
  422.                     $v3 ? $parameter['schema'] = ['type' => 'string'] : $parameter['type'] = 'string';
  423.                     $pathOperation['parameters'][] = $parameter;
  424.                     $parametersMemory[] = $parameterName;
  425.                 }
  427.                 if ($parameters = $this->getFiltersParameters($v3, $resourceClass, $operationName, $resourceMetadata)) {
  428.                     foreach ($parameters as $parameter) {
  429.                         if (!\in_array($parameter['name'], $parametersMemory, true)) {
  430.                             $pathOperation['parameters'][] = $parameter;
  431.                         }
  432.                     }
  433.                 }
  434.             } else {
  435.                 $pathOperation['parameters'] ?? $pathOperation['parameters'] = $this->getFiltersParameters($v3, $resourceClass, $operationName, $resourceMetadata);
  436.             }
  438.             $this->addPaginationParameters($v3, $resourceMetadata, OperationType::COLLECTION, $operationName, $pathOperation);
  440.             return $pathOperation;
  441.         }
  443.         $outputResourseShortName = $resourceMetadata->getItemOperations()[$operationName]['output']['name'] ?? $resourceShortName;
  444.         $pathOperation['summary'] ?? $pathOperation['summary'] = sprintf('Retrieves a %s resource.', $outputResourseShortName);
  446.         $pathOperation = $this->addItemOperationParameters($v3, $pathOperation, $operationType, $operationName, $resourceMetadata, $resourceClass);
  448.         $successResponse = ['description' => sprintf('%s resource response', $outputResourseShortName)];
  449.         [$successResponse] = $this->addSchemas($v3, $successResponse, $definitions, $resourceClass, $operationType, $operationName, $mimeTypes);
  451.         $pathOperation['responses'] ?? $pathOperation['responses'] = [
  452.             $successStatus => $successResponse,
  453.             '404' => ['description' => 'Resource not found'],
  454.         ];
  456.         return $pathOperation;
  457.     }
  459.     private function addPaginationParameters(bool $v3, ResourceMetadata $resourceMetadata, string $operationType, string $operationName, \ArrayObject $pathOperation)
  460.     {
  461.         if ($this->paginationEnabled && $resourceMetadata->getTypedOperationAttribute($operationType, $operationName, 'pagination_enabled', true, true)) {
  462.             $paginationParameter = [
  463.                 'name' => $this->paginationPageParameterName,
  464.                 'in' => 'query',
  465.                 'required' => false,
  466.                 'description' => 'The collection page number',
  467.             ];
  468.             $v3 ? $paginationParameter['schema'] = [
  469.                 'type' => 'integer',
  470.                 'default' => 1,
  471.             ] : $paginationParameter['type'] = 'integer';
  472.             $pathOperation['parameters'][] = $paginationParameter;
  474.             if ($resourceMetadata->getTypedOperationAttribute($operationType, $operationName, 'pagination_client_items_per_page', $this->clientItemsPerPage, true)) {
  475.                 $itemPerPageParameter = [
  476.                     'name' => $this->itemsPerPageParameterName,
  477.                     'in' => 'query',
  478.                     'required' => false,
  479.                     'description' => 'The number of items per page',
  480.                 ];
  481.                 if ($v3) {
  482.                     $itemPerPageParameter['schema'] = [
  483.                         'type' => 'integer',
  484.                         'default' => $resourceMetadata->getTypedOperationAttribute($operationType, $operationName, 'pagination_items_per_page', 30, true),
  485.                         'minimum' => 0,
  486.                     ];
  488.                     $maxItemsPerPage = $resourceMetadata->getTypedOperationAttribute($operationType, $operationName, 'maximum_items_per_page', null, true);
  489.                     if (null !== $maxItemsPerPage) {
  490.                         @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);
  491.                     }
  492.                     $maxItemsPerPage = $resourceMetadata->getTypedOperationAttribute($operationType, $operationName, 'pagination_maximum_items_per_page', $maxItemsPerPage, true);
  494.                     if (null !== $maxItemsPerPage) {
  495.                         $itemPerPageParameter['schema']['maximum'] = $maxItemsPerPage;
  496.                     }
  497.                 } else {
  498.                     $itemPerPageParameter['type'] = 'integer';
  499.                 }
  501.                 $pathOperation['parameters'][] = $itemPerPageParameter;
  502.             }
  503.         }
  505.         if ($this->paginationEnabled && $resourceMetadata->getTypedOperationAttribute($operationType, $operationName, 'pagination_client_enabled', $this->paginationClientEnabled, true)) {
  506.             $paginationEnabledParameter = [
  507.                 'name' => $this->paginationClientEnabledParameterName,
  508.                 'in' => 'query',
  509.                 'required' => false,
  510.                 'description' => 'Enable or disable pagination',
  511.             ];
  512.             $v3 ? $paginationEnabledParameter['schema'] = ['type' => 'boolean'] : $paginationEnabledParameter['type'] = 'boolean';
  513.             $pathOperation['parameters'][] = $paginationEnabledParameter;
  514.         }
  515.     }
  517.     /**
  518.      * @throws ResourceClassNotFoundException
  519.      */
  520.     private function addSubresourceOperation(bool $v3, array $subresourceOperation, \ArrayObject $definitions, string $operationId, ResourceMetadata $resourceMetadata): \ArrayObject
  521.     {
  522.         $operationName = 'get'; // TODO: we might want to extract that at some point to also support other subresource operations
  523.         $collection = $subresourceOperation['collection'] ?? false;
  525.         $subResourceMetadata = $this->resourceMetadataFactory->create($subresourceOperation['resource_class']);
  527.         $pathOperation = new \ArrayObject([]);
  528.         $pathOperation['tags'] = $subresourceOperation['shortNames'];
  529.         $pathOperation['operationId'] = $operationId;
  530.         $pathOperation['summary'] = sprintf('Retrieves %s%s resource%s.', $subresourceOperation['collection'] ? 'the collection of ' : 'a ', $subresourceOperation['shortNames'][0], $subresourceOperation['collection'] ? 's' : '');
  532.         if (null === $this->formatsProvider) {
  533.             // TODO: Subresource operation metadata aren't available by default, for now we have to fallback on default formats.
  534.             // TODO: A better approach would be to always populate the subresource operation array.
  535.             $subResourceMetadata = $this
  536.                 ->resourceMetadataFactory
  537.                 ->create($subresourceOperation['resource_class']);
  539.             if ($this->resourceMetadataFactory instanceof ResourceMetadataCollectionFactoryInterface) {
  540.                 $subResourceMetadata = $this->transformResourceToResourceMetadata($subResourceMetadata[0]);
  541.             }
  543.             $responseFormats = $subResourceMetadata->getTypedOperationAttribute(OperationType::SUBRESOURCE, $operationName, 'output_formats', $this->formats, true);
  544.         } else {
  545.             $responseFormats = $this->formatsProvider->getFormatsFromOperation($subresourceOperation['resource_class'], $operationName, OperationType::SUBRESOURCE);
  546.         }
  548.         $mimeTypes = $this->flattenMimeTypes($responseFormats);
  550.         if (!$v3) {
  551.             $pathOperation['produces'] = array_keys($mimeTypes);
  552.         }
  554.         $successResponse = [
  555.             'description' => sprintf('%s %s response', $subresourceOperation['shortNames'][0], $collection ? 'collection' : 'resource'),
  556.         ];
  557.         [$successResponse] = $this->addSchemas($v3, $successResponse, $definitions, $subresourceOperation['resource_class'], OperationType::SUBRESOURCE, $operationName, $mimeTypes, Schema::TYPE_OUTPUT, $collection);
  559.         $pathOperation['responses'] = ['200' => $successResponse, '404' => ['description' => 'Resource not found']];
  561.         // Avoid duplicates parameters when there is a filter on a subresource identifier
  562.         $parametersMemory = [];
  563.         $pathOperation['parameters'] = [];
  564.         foreach ($subresourceOperation['identifiers'] as $parameterName => [$class, $identifier, $hasIdentifier]) {
  565.             if (false === strpos($subresourceOperation['path'], sprintf('{%s}', $parameterName))) {
  566.                 continue;
  567.             }
  569.             $parameter = ['name' => $parameterName, 'in' => 'path', 'required' => true];
  570.             $v3 ? $parameter['schema'] = ['type' => 'string'] : $parameter['type'] = 'string';
  571.             $pathOperation['parameters'][] = $parameter;
  572.             $parametersMemory[] = $parameterName;
  573.         }
  575.         if ($parameters = $this->getFiltersParameters($v3, $subresourceOperation['resource_class'], $operationName, $subResourceMetadata)) {
  576.             foreach ($parameters as $parameter) {
  577.                 if (!\in_array($parameter['name'], $parametersMemory, true)) {
  578.                     $pathOperation['parameters'][] = $parameter;
  579.                 }
  580.             }
  581.         }
  583.         if ($subresourceOperation['collection']) {
  584.             $this->addPaginationParameters($v3, $subResourceMetadata, OperationType::SUBRESOURCE, $subresourceOperation['operation_name'], $pathOperation);
  585.         }
  587.         return $pathOperation;
  588.     }
  590.     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
  591.     {
  592.         if (!$v3) {
  593.             $pathOperation['consumes'] ?? $pathOperation['consumes'] = array_keys($requestMimeTypes);
  594.             $pathOperation['produces'] ?? $pathOperation['produces'] = array_keys($responseMimeTypes);
  595.         }
  597.         $pathOperation['summary'] ?? $pathOperation['summary'] = sprintf('Creates a %s resource.', $resourceShortName);
  599.         $identifiers = (array) $resourceMetadata
  600.                 ->getTypedOperationAttribute($operationType, $operationName, 'identifiers', [], false);
  602.         $pathOperation = $this->addItemOperationParameters($v3, $pathOperation, $operationType, $operationName, $resourceMetadata, $resourceClass, OperationType::ITEM === $operationType ? false : true);
  604.         $successResponse = ['description' => sprintf('%s resource created', $resourceShortName)];
  605.         [$successResponse, $defined] = $this->addSchemas($v3, $successResponse, $definitions, $resourceClass, $operationType, $operationName, $responseMimeTypes);
  607.         if ($defined && $v3 && ($links[$key = 'get'.ucfirst($resourceShortName).ucfirst(OperationType::ITEM)] ?? null)) {
  608.             $successResponse['links'] = [ucfirst($key) => $links[$key]];
  609.         }
  611.         $pathOperation['responses'] ?? $pathOperation['responses'] = [
  612.             (string) $resourceMetadata->getTypedOperationAttribute($operationType, $operationName, 'status', '201') => $successResponse,
  613.             '400' => ['description' => 'Invalid input'],
  614.             '404' => ['description' => 'Resource not found'],
  615.             '422' => ['description' => 'Unprocessable entity'],
  616.         ];
  618.         return $this->addRequestBody($v3, $pathOperation, $definitions, $resourceClass, $resourceShortName, $operationType, $operationName, $requestMimeTypes);
  619.     }
  621.     private function updatePutOperation(bool $v3, \ArrayObject $pathOperation, array $requestMimeTypes, array $responseMimeTypes, string $operationType, ResourceMetadata $resourceMetadata, string $resourceClass, string $resourceShortName, string $operationName, \ArrayObject $definitions): \ArrayObject
  622.     {
  623.         if (!$v3) {
  624.             $pathOperation['consumes'] ?? $pathOperation['consumes'] = array_keys($requestMimeTypes);
  625.             $pathOperation['produces'] ?? $pathOperation['produces'] = array_keys($responseMimeTypes);
  626.         }
  628.         $pathOperation['summary'] ?? $pathOperation['summary'] = sprintf('Replaces the %s resource.', $resourceShortName);
  630.         $pathOperation = $this->addItemOperationParameters($v3, $pathOperation, $operationType, $operationName, $resourceMetadata, $resourceClass);
  632.         $successResponse = ['description' => sprintf('%s resource updated', $resourceShortName)];
  633.         [$successResponse] = $this->addSchemas($v3, $successResponse, $definitions, $resourceClass, $operationType, $operationName, $responseMimeTypes);
  635.         $pathOperation['responses'] ?? $pathOperation['responses'] = [
  636.             (string) $resourceMetadata->getTypedOperationAttribute($operationType, $operationName, 'status', '200') => $successResponse,
  637.             '400' => ['description' => 'Invalid input'],
  638.             '404' => ['description' => 'Resource not found'],
  639.             '422' => ['description' => 'Unprocessable entity'],
  640.         ];
  642.         return $this->addRequestBody($v3, $pathOperation, $definitions, $resourceClass, $resourceShortName, $operationType, $operationName, $requestMimeTypes, true);
  643.     }
  645.     private function addRequestBody(bool $v3, \ArrayObject $pathOperation, \ArrayObject $definitions, string $resourceClass, string $resourceShortName, string $operationType, string $operationName, array $requestMimeTypes, bool $put = false)
  646.     {
  647.         if (isset($pathOperation['requestBody'])) {
  648.             return $pathOperation;
  649.         }
  651.         [$message, $defined] = $this->addSchemas($v3, [], $definitions, $resourceClass, $operationType, $operationName, $requestMimeTypes, Schema::TYPE_INPUT);
  652.         if (!$defined) {
  653.             return $pathOperation;
  654.         }
  656.         $description = sprintf('The %s %s resource', $put ? 'updated' : 'new', $resourceShortName);
  657.         if ($v3) {
  658.             $pathOperation['requestBody'] = $message + ['description' => $description];
  660.             return $pathOperation;
  661.         }
  663.         if (!$this->hasBodyParameter($pathOperation['parameters'] ?? [])) {
  664.             $pathOperation['parameters'][] = [
  665.                 'name' => lcfirst($resourceShortName),
  666.                 'in' => 'body',
  667.                 'description' => $description,
  668.             ] + $message;
  669.         }
  671.         return $pathOperation;
  672.     }
  674.     private function hasBodyParameter(array $parameters): bool
  675.     {
  676.         foreach ($parameters as $parameter) {
  677.             if (\array_key_exists('in', $parameter) && 'body' === $parameter['in']) {
  678.                 return true;
  679.             }
  680.         }
  682.         return false;
  683.     }
  685.     private function updateDeleteOperation(bool $v3, \ArrayObject $pathOperation, string $resourceShortName, string $operationType, string $operationName, ResourceMetadata $resourceMetadata, string $resourceClass): \ArrayObject
  686.     {
  687.         $pathOperation['summary'] ?? $pathOperation['summary'] = sprintf('Removes the %s resource.', $resourceShortName);
  688.         $pathOperation['responses'] ?? $pathOperation['responses'] = [
  689.             (string) $resourceMetadata->getTypedOperationAttribute($operationType, $operationName, 'status', '204') => ['description' => sprintf('%s resource deleted', $resourceShortName)],
  690.             '404' => ['description' => 'Resource not found'],
  691.         ];
  693.         return $this->addItemOperationParameters($v3, $pathOperation, $operationType, $operationName, $resourceMetadata, $resourceClass);
  694.     }
  696.     private function addItemOperationParameters(bool $v3, \ArrayObject $pathOperation, string $operationType, string $operationName, ResourceMetadata $resourceMetadata, string $resourceClass, bool $isPost = false): \ArrayObject
  697.     {
  698.         $identifiers = (array) $resourceMetadata
  699.                 ->getTypedOperationAttribute($operationType, $operationName, 'identifiers', [], false);
  701.         // Auto-generated routes in API Platform < 2.7 are considered as collection, hotfix this as the OpenApi Factory supports new operations anyways.
  702.         // this also fixes a bug where we could not create POST item operations in API P 2.6
  703.         if (OperationType::ITEM === $operationType && $isPost) {
  704.             $operationType = OperationType::COLLECTION;
  705.         }
  707.         if (!$identifiers && OperationType::COLLECTION !== $operationType) {
  708.             try {
  709.                 $identifiers = $this->identifiersExtractor->getIdentifiersFromResourceClass($resourceClass);
  710.             } catch (RuntimeException $e) {
  711.                 // Ignore exception here
  712.             } catch (ResourceClassNotFoundException $e) {
  713.                 if (false === $this->legacyMode) {
  714.                     // Skipping these, swagger is not compatible with post 2.7 resource metadata
  715.                     return $pathOperation;
  716.                 }
  717.                 throw $e;
  718.             }
  719.         }
  721.         if (\count($identifiers) > 1 ? $resourceMetadata->getItemOperationAttribute($operationName, 'composite_identifier', true, true) : false) {
  722.             $identifiers = ['id'];
  723.         }
  725.         if (!$identifiers && OperationType::COLLECTION === $operationType) {
  726.             return $pathOperation;
  727.         }
  729.         if (!isset($pathOperation['parameters'])) {
  730.             $pathOperation['parameters'] = [];
  731.         }
  733.         foreach ($identifiers as $parameterName => $identifier) {
  734.             $parameter = [
  735.                 'name' => \is_string($parameterName) ? $parameterName : $identifier,
  736.                 'in' => 'path',
  737.                 'required' => true,
  738.             ];
  739.             $v3 ? $parameter['schema'] = ['type' => 'string'] : $parameter['type'] = 'string';
  740.             $pathOperation['parameters'][] = $parameter;
  741.         }
  743.         return $pathOperation;
  744.     }
  746.     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
  747.     {
  748.         $schema = new Schema($v3 ? Schema::VERSION_OPENAPI : Schema::VERSION_SWAGGER);
  749.         $schema->setDefinitions($definitions);
  751.         if ($this->jsonSchemaFactory instanceof SchemaFactoryInterface) {
  752.             $operation = $operationName ? (new class() extends HttpOperation {})->withName($operationName) : null;
  754.             return $this->jsonSchemaFactory->buildSchema($resourceClass, $format, $type, $operation, $schema, $serializerContext, $forceCollection);
  755.         }
  757.         return $this->jsonSchemaFactory->buildSchema($resourceClass, $format, $type, $operationType, $operationName, $schema, $serializerContext, $forceCollection);
  758.     }
  760.     private function computeDoc(bool $v3, Documentation $documentation, \ArrayObject $definitions, \ArrayObject $paths, array $context): array
  761.     {
  762.         $baseUrl = $context[self::BASE_URL] ?? $this->defaultContext[self::BASE_URL];
  764.         if ($v3) {
  765.             $docs = ['openapi' => self::OPENAPI_VERSION];
  766.             if ('/' !== $baseUrl && '' !== $baseUrl) {
  767.                 $docs['servers'] = [['url' => $baseUrl]];
  768.             }
  769.         } else {
  770.             $docs = [
  771.                 'swagger' => self::SWAGGER_VERSION,
  772.                 'basePath' => $baseUrl,
  773.             ];
  774.         }
  776.         $docs += [
  777.             'info' => [
  778.                 'title' => $documentation->getTitle(),
  779.                 'version' => $documentation->getVersion(),
  780.             ],
  781.             'paths' => $paths,
  782.         ];
  784.         if ('' !== $description = $documentation->getDescription()) {
  785.             $docs['info']['description'] = $description;
  786.         }
  788.         $securityDefinitions = [];
  789.         $security = [];
  791.         if ($this->oauthEnabled) {
  792.             $oauthAttributes = [
  793.                 'authorizationUrl' => $this->oauthAuthorizationUrl,
  794.                 'scopes' => new \ArrayObject($this->oauthScopes),
  795.             ];
  797.             if ($this->oauthTokenUrl) {
  798.                 $oauthAttributes['tokenUrl'] = $this->oauthTokenUrl;
  799.             }
  801.             $securityDefinitions['oauth'] = [
  802.                 'type' => $this->oauthType,
  803.                 'description' => sprintf(
  804.                     'OAuth 2.0 %s Grant',
  805.                     strtolower(preg_replace('/[A-Z]/', ' \\0', lcfirst($this->oauthFlow)))
  806.                 ),
  807.             ];
  809.             if ($v3) {
  810.                 $securityDefinitions['oauth']['flows'] = [
  811.                     $this->oauthFlow => $oauthAttributes,
  812.                 ];
  813.             } else {
  814.                 $securityDefinitions['oauth']['flow'] = $this->oauthFlow;
  815.                 $securityDefinitions['oauth'] = array_merge($securityDefinitions['oauth'], $oauthAttributes);
  816.             }
  818.             $security[] = ['oauth' => []];
  819.         }
  821.         foreach ($this->apiKeys as $key => $apiKey) {
  822.             $name = $apiKey['name'];
  823.             $type = $apiKey['type'];
  825.             $securityDefinitions[$key] = [
  826.                 'type' => 'apiKey',
  827.                 'in' => $type,
  828.                 'description' => sprintf('Value for the %s %s', $name, 'query' === $type ? sprintf('%s parameter', $type) : $type),
  829.                 'name' => $name,
  830.             ];
  832.             $security[] = [$key => []];
  833.         }
  835.         if ($securityDefinitions && $security) { // @phpstan-ignore-line false positive
  836.             $docs['security'] = $security;
  837.             if (!$v3) {
  838.                 $docs['securityDefinitions'] = $securityDefinitions;
  839.             }
  840.         }
  842.         if ($v3) {
  843.             if (\count($definitions) + \count($securityDefinitions)) {
  844.                 $docs['components'] = [];
  845.                 if (\count($definitions)) {
  846.                     $docs['components']['schemas'] = $definitions;
  847.                 }
  848.                 if (\count($securityDefinitions)) {
  849.                     $docs['components']['securitySchemes'] = $securityDefinitions;
  850.                 }
  851.             }
  852.         } elseif (\count($definitions) > 0) {
  853.             $docs['definitions'] = $definitions;
  854.         }
  856.         return $docs;
  857.     }
  859.     /**
  860.      * Gets parameters corresponding to enabled filters.
  861.      */
  862.     private function getFiltersParameters(bool $v3, string $resourceClass, string $operationName, ResourceMetadata $resourceMetadata): array
  863.     {
  864.         if (null === $this->filterLocator) {
  865.             return [];
  866.         }
  868.         $parameters = [];
  869.         $resourceFilters = $resourceMetadata->getCollectionOperationAttribute($operationName, 'filters', [], true);
  870.         foreach ($resourceFilters as $filterId) {
  871.             if (!$filter = $this->getFilter($filterId)) {
  872.                 continue;
  873.             }
  875.             foreach ($filter->getDescription($resourceClass) as $name => $data) {
  876.                 $parameter = [
  877.                     'name' => $name,
  878.                     'in' => 'query',
  879.                     'required' => $data['required'],
  880.                 ];
  882.                 $type = \in_array($data['type'], Type::$builtinTypes, true) ? $this->jsonSchemaTypeFactory->getType(new Type($data['type'], false, null, $data['is_collection'] ?? false)) : ['type' => 'string'];
  883.                 $v3 ? $parameter['schema'] = $type : $parameter += $type;
  885.                 if ($v3 && isset($data['schema'])) {
  886.                     $parameter['schema'] = $data['schema'];
  887.                 }
  889.                 if ('array' === ($type['type'] ?? '')) {
  890.                     $deepObject = \in_array($data['type'], [Type::BUILTIN_TYPE_ARRAY, Type::BUILTIN_TYPE_OBJECT], true);
  892.                     if ($v3) {
  893.                         $parameter['style'] = $deepObject ? 'deepObject' : 'form';
  894.                         $parameter['explode'] = true;
  895.                     } else {
  896.                         $parameter['collectionFormat'] = $deepObject ? 'csv' : 'multi';
  897.                     }
  898.                 }
  900.                 $key = $v3 ? 'openapi' : 'swagger';
  901.                 if (isset($data[$key])) {
  902.                     $parameter = $data[$key] + $parameter;
  903.                 }
  905.                 $parameters[] = $parameter;
  906.             }
  907.         }
  909.         return $parameters;
  910.     }
  912.     /**
  913.      * {@inheritdoc}
  914.      */
  915.     public function supportsNormalization($data, $format = null, array $context = []): bool
  916.     {
  917.         return self::FORMAT === $format && ($data instanceof Documentation || $this->openApiNormalizer && $data instanceof OpenApi);
  918.     }
  920.     /**
  921.      * {@inheritdoc}
  922.      */
  923.     public function hasCacheableSupportsMethod(): bool
  924.     {
  925.         return true;
  926.     }
  928.     private function flattenMimeTypes(array $responseFormats): array
  929.     {
  930.         $responseMimeTypes = [];
  931.         foreach ($responseFormats as $responseFormat => $mimeTypes) {
  932.             foreach ($mimeTypes as $mimeType) {
  933.                 $responseMimeTypes[$mimeType] = $responseFormat;
  934.             }
  935.         }
  937.         return $responseMimeTypes;
  938.     }
  940.     /**
  941.      * https://github.com/OAI/OpenAPI-Specification/blob/master/versions/3.0.0.md#linkObject.
  942.      */
  943.     private function getLinkObject(string $resourceClass, string $operationId, string $path): array
  944.     {
  945.         $linkObject = $identifiers = [];
  946.         foreach ($this->propertyNameCollectionFactory->create($resourceClass) as $propertyName) {
  947.             $propertyMetadata = $this->propertyMetadataFactory->create($resourceClass, $propertyName);
  948.             if (!$propertyMetadata->isIdentifier()) {
  949.                 continue;
  950.             }
  952.             $linkObject['parameters'][$propertyName] = sprintf('$response.body#/%s', $propertyName);
  953.             $identifiers[] = $propertyName;
  954.         }
  956.         if (!$linkObject) {
  957.             return [];
  958.         }
  959.         $linkObject['operationId'] = $operationId;
  960.         $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);
  962.         return $linkObject;
  963.     }
  964. }