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

Open in your IDE?
  1. <?php
  2. /*
  3.  * This file is part of the API Platform project.
  4.  *
  5.  * (c) Kévin Dunglas <[email protected]>
  6.  *
  7.  * For the full copyright and license information, please view the LICENSE
  8.  * file that was distributed with this source code.
  9.  */
  10. declare(strict_types=1);
  11. namespace ApiPlatform\Core\Swagger\Serializer;
  12. use ApiPlatform\Core\Api\FilterCollection;
  13. use ApiPlatform\Core\Api\FilterLocatorTrait;
  14. use ApiPlatform\Core\Api\FormatsProviderInterface;
  15. use ApiPlatform\Core\Api\IdentifiersExtractorInterface;
  16. use ApiPlatform\Core\Api\OperationAwareFormatsProviderInterface;
  17. use ApiPlatform\Core\Api\OperationMethodResolverInterface;
  18. use ApiPlatform\Core\Api\OperationType;
  19. use ApiPlatform\Core\Api\ResourceClassResolverInterface;
  20. use ApiPlatform\Core\Api\UrlGeneratorInterface;
  21. use ApiPlatform\Core\JsonSchema\SchemaFactory as LegacySchemaFactory;
  22. use ApiPlatform\Core\JsonSchema\SchemaFactoryInterface as LegacySchemaFactoryInterface;
  23. use ApiPlatform\Core\Metadata\Property\Factory\PropertyMetadataFactoryInterface;
  24. use ApiPlatform\Core\Metadata\Property\Factory\PropertyNameCollectionFactoryInterface;
  25. use ApiPlatform\Core\Metadata\Resource\ApiResourceToLegacyResourceMetadataTrait;
  26. use ApiPlatform\Core\Metadata\Resource\Factory\ResourceMetadataFactoryInterface;
  27. use ApiPlatform\Core\Metadata\Resource\ResourceMetadata;
  28. use ApiPlatform\Core\Operation\Factory\SubresourceOperationFactoryInterface;
  29. use ApiPlatform\Documentation\Documentation;
  30. use ApiPlatform\Exception\ResourceClassNotFoundException;
  31. use ApiPlatform\Exception\RuntimeException;
  32. use ApiPlatform\JsonSchema\Schema;
  33. use ApiPlatform\JsonSchema\SchemaFactory;
  34. use ApiPlatform\JsonSchema\SchemaFactoryInterface;
  35. use ApiPlatform\JsonSchema\TypeFactory;
  36. use ApiPlatform\JsonSchema\TypeFactoryInterface;
  37. use ApiPlatform\Metadata\HttpOperation;
  38. use ApiPlatform\Metadata\Resource\Factory\ResourceMetadataCollectionFactoryInterface;
  39. use ApiPlatform\OpenApi\OpenApi;
  40. use ApiPlatform\OpenApi\Serializer\ApiGatewayNormalizer;
  41. use ApiPlatform\PathResolver\OperationPathResolverInterface;
  42. use Psr\Container\ContainerInterface;
  43. use Symfony\Component\PropertyInfo\Type;
  44. use Symfony\Component\Serializer\NameConverter\NameConverterInterface;
  45. use Symfony\Component\Serializer\Normalizer\CacheableSupportsMethodInterface;
  46. use Symfony\Component\Serializer\Normalizer\NormalizerInterface;
  47. /**
  48.  * Generates an OpenAPI specification (formerly known as Swagger). OpenAPI v2 and v3 are supported.
  49.  *
  50.  * @author Amrouche Hamza <[email protected]>
  51.  * @author Teoh Han Hui <[email protected]>
  52.  * @author Kévin Dunglas <[email protected]>
  53.  * @author Anthony GRASSIOT <[email protected]>
  54.  */
  55. final class DocumentationNormalizer implements NormalizerInterfaceCacheableSupportsMethodInterface
  56. {
  57.     use ApiResourceToLegacyResourceMetadataTrait;
  58.     use FilterLocatorTrait;
  59.     public const FORMAT 'json';
  60.     public const BASE_URL 'base_url';
  61.     public const SPEC_VERSION 'spec_version';
  62.     public const OPENAPI_VERSION '3.0.2';
  63.     public const SWAGGER_DEFINITION_NAME 'swagger_definition_name';
  64.     public const SWAGGER_VERSION '2.0';
  65.     /**
  66.      * @deprecated
  67.      */
  68.     public const ATTRIBUTE_NAME 'swagger_context';
  69.     private $resourceMetadataFactory;
  70.     private $propertyNameCollectionFactory;
  71.     private $propertyMetadataFactory;
  72.     private $operationMethodResolver;
  73.     private $operationPathResolver;
  74.     private $oauthEnabled;
  75.     private $oauthType;
  76.     private $oauthFlow;
  77.     private $oauthTokenUrl;
  78.     private $oauthAuthorizationUrl;
  79.     private $oauthScopes;
  80.     private $apiKeys;
  81.     private $subresourceOperationFactory;
  82.     private $paginationEnabled;
  83.     private $paginationPageParameterName;
  84.     private $clientItemsPerPage;
  85.     private $itemsPerPageParameterName;
  86.     private $paginationClientEnabled;
  87.     private $paginationClientEnabledParameterName;
  88.     private $formats;
  89.     private $formatsProvider;
  90.     /**
  91.      * @var SchemaFactoryInterface|LegacySchemaFactoryInterface
  92.      */
  93.     private $jsonSchemaFactory;
  94.     /**
  95.      * @var TypeFactoryInterface
  96.      */
  97.     private $jsonSchemaTypeFactory;
  98.     private $defaultContext = [
  99.         self::BASE_URL => '/',
  100.         ApiGatewayNormalizer::API_GATEWAY => false,
  101.     ];
  102.     private $identifiersExtractor;
  103.     private $openApiNormalizer;
  104.     private $legacyMode;
  105.     /**
  106.      * @param LegacySchemaFactoryInterface|SchemaFactoryInterface|ResourceClassResolverInterface|null $jsonSchemaFactory
  107.      * @param ContainerInterface|FilterCollection|null                                                $filterLocator
  108.      * @param array|OperationAwareFormatsProviderInterface                                            $formats
  109.      * @param mixed|null                                                                              $jsonSchemaTypeFactory
  110.      * @param int[]                                                                                   $swaggerVersions
  111.      * @param mixed                                                                                   $resourceMetadataFactory
  112.      */
  113.     public function __construct($resourceMetadataFactoryPropertyNameCollectionFactoryInterface $propertyNameCollectionFactoryPropertyMetadataFactoryInterface $propertyMetadataFactory$jsonSchemaFactory null$jsonSchemaTypeFactory nullOperationPathResolverInterface $operationPathResolver nullUrlGeneratorInterface $urlGenerator null$filterLocator nullNameConverterInterface $nameConverter nullbool $oauthEnabled falsestring $oauthType ''string $oauthFlow ''string $oauthTokenUrl ''string $oauthAuthorizationUrl '', array $oauthScopes = [], array $apiKeys = [], SubresourceOperationFactoryInterface $subresourceOperationFactory nullbool $paginationEnabled truestring $paginationPageParameterName 'page'bool $clientItemsPerPage falsestring $itemsPerPageParameterName 'itemsPerPage'$formats = [], bool $paginationClientEnabled falsestring $paginationClientEnabledParameterName 'pagination', array $defaultContext = [], array $swaggerVersions = [23], IdentifiersExtractorInterface $identifiersExtractor nullNormalizerInterface $openApiNormalizer nullbool $legacyMode false)
  114.     {
  115.         if ($jsonSchemaTypeFactory instanceof OperationMethodResolverInterface) {
  116.             @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);
  117.             $this->operationMethodResolver $jsonSchemaTypeFactory;
  118.             $this->jsonSchemaTypeFactory = new TypeFactory();
  119.         } else {
  120.             $this->jsonSchemaTypeFactory $jsonSchemaTypeFactory ?? new TypeFactory();
  121.         }
  122.         if ($jsonSchemaFactory instanceof ResourceClassResolverInterface) {
  123.             @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);
  124.         }
  125.         if (null === $jsonSchemaFactory || $jsonSchemaFactory instanceof ResourceClassResolverInterface) {
  126.             if ($resourceMetadataFactory instanceof ResourceMetadataFactoryInterface) {
  127.                 $jsonSchemaFactory = new LegacySchemaFactory($this->jsonSchemaTypeFactory$resourceMetadataFactory$propertyNameCollectionFactory$propertyMetadataFactory$nameConverter);
  128.             } else {
  129.                 $jsonSchemaFactory = new SchemaFactory($this->jsonSchemaTypeFactory$resourceMetadataFactory$propertyNameCollectionFactory$propertyMetadataFactory$nameConverter);
  130.             }
  131.             $this->jsonSchemaTypeFactory->setSchemaFactory($jsonSchemaFactory);
  132.         }
  133.         $this->jsonSchemaFactory $jsonSchemaFactory;
  134.         if ($nameConverter) {
  135.             @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);
  136.         }
  137.         if ($urlGenerator) {
  138.             @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);
  139.         }
  140.         if ($formats instanceof FormatsProviderInterface) {
  141.             @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);
  142.             $this->formatsProvider $formats;
  143.         } else {
  144.             $this->formats $formats;
  145.         }
  146.         $this->setFilterLocator($filterLocatortrue);
  147.         if ($resourceMetadataFactory instanceof ResourceMetadataFactoryInterface) {
  148.             trigger_deprecation('api-platform/core''2.7'sprintf('Use "%s" instead of "%s".'ResourceMetadataCollectionFactoryInterface::class, ResourceMetadataFactoryInterface::class));
  149.         }
  150.         $this->resourceMetadataFactory $resourceMetadataFactory;
  151.         $this->propertyNameCollectionFactory $propertyNameCollectionFactory;
  152.         $this->propertyMetadataFactory $propertyMetadataFactory;
  153.         $this->operationPathResolver $operationPathResolver;
  154.         $this->oauthEnabled $oauthEnabled;
  155.         $this->oauthType $oauthType;
  156.         $this->oauthFlow $oauthFlow;
  157.         $this->oauthTokenUrl $oauthTokenUrl;
  158.         $this->oauthAuthorizationUrl $oauthAuthorizationUrl;
  159.         $this->oauthScopes $oauthScopes;
  160.         $this->subresourceOperationFactory $subresourceOperationFactory;
  161.         $this->paginationEnabled $paginationEnabled;
  162.         $this->paginationPageParameterName $paginationPageParameterName;
  163.         $this->apiKeys $apiKeys;
  164.         $this->clientItemsPerPage $clientItemsPerPage;
  165.         $this->itemsPerPageParameterName $itemsPerPageParameterName;
  166.         $this->paginationClientEnabled $paginationClientEnabled;
  167.         $this->paginationClientEnabledParameterName $paginationClientEnabledParameterName;
  168.         $this->defaultContext[self::SPEC_VERSION] = $swaggerVersions[0] ?? 2;
  169.         $this->defaultContext array_merge($this->defaultContext$defaultContext);
  170.         $this->identifiersExtractor $identifiersExtractor;
  171.         $this->openApiNormalizer $openApiNormalizer;
  172.         $this->legacyMode $legacyMode;
  173.     }
  174.     /**
  175.      * {@inheritdoc}
  176.      *
  177.      * @return array|string|int|float|bool|\ArrayObject|null
  178.      */
  179.     public function normalize($object$format null, array $context = [])
  180.     {
  181.         if ($object instanceof OpenApi) {
  182.             @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);
  183.             return $this->openApiNormalizer->normalize($object$format$context);
  184.         }
  185.         $v3 === ($context['spec_version'] ?? $this->defaultContext['spec_version']) && !($context['api_gateway'] ?? $this->defaultContext['api_gateway']);
  186.         $definitions = new \ArrayObject();
  187.         $paths = new \ArrayObject();
  188.         $links = new \ArrayObject();
  189.         if ($this->resourceMetadataFactory instanceof ResourceMetadataCollectionFactoryInterface) {
  190.             foreach ($object->getResourceNameCollection() as $resourceClass) {
  191.                 $resourceMetadataCollection $this->resourceMetadataFactory->create($resourceClass);
  192.                 foreach ($resourceMetadataCollection as $i => $resourceMetadata) {
  193.                     $resourceMetadata $this->transformResourceToResourceMetadata($resourceMetadata);
  194.                     // Items needs to be parsed first to be able to reference the lines from the collection operation
  195.                     $this->addPaths($v3$paths$definitions$resourceClass$resourceMetadata->getShortName(), $resourceMetadataOperationType::ITEM$links);
  196.                     $this->addPaths($v3$paths$definitions$resourceClass$resourceMetadata->getShortName(), $resourceMetadataOperationType::COLLECTION$links);
  197.                 }
  198.             }
  199.             $definitions->ksort();
  200.             $paths->ksort();
  201.             return $this->computeDoc($v3$object$definitions$paths$context);
  202.         }
  203.         foreach ($object->getResourceNameCollection() as $resourceClass) {
  204.             $resourceMetadata $this->resourceMetadataFactory->create($resourceClass);
  205.             if ($this->identifiersExtractor) {
  206.                 $identifiers = [];
  207.                 if ($resourceMetadata->getItemOperations()) {
  208.                     $identifiers $this->identifiersExtractor->getIdentifiersFromResourceClass($resourceClass);
  209.                 }
  210.                 $resourceMetadata $resourceMetadata->withAttributes(($resourceMetadata->getAttributes() ?: []) + ['identifiers' => $identifiers]);
  211.             }
  212.             $resourceShortName $resourceMetadata->getShortName();
  213.             // Items needs to be parsed first to be able to reference the lines from the collection operation
  214.             $this->addPaths($v3$paths$definitions$resourceClass$resourceShortName$resourceMetadataOperationType::ITEM$links);
  215.             $this->addPaths($v3$paths$definitions$resourceClass$resourceShortName$resourceMetadataOperationType::COLLECTION$links);
  216.             if (null === $this->subresourceOperationFactory) {
  217.                 continue;
  218.             }
  219.             foreach ($this->subresourceOperationFactory->create($resourceClass) as $operationId => $subresourceOperation) {
  220.                 $method $resourceMetadata->getTypedOperationAttribute(OperationType::SUBRESOURCE$subresourceOperation['operation_name'], 'method''GET');
  221.                 $paths[$this->getPath($subresourceOperation['shortNames'][0], $subresourceOperation['route_name'], $subresourceOperationOperationType::SUBRESOURCE)][strtolower($method)] = $this->addSubresourceOperation($v3$subresourceOperation$definitions$operationId$resourceMetadata);
  222.             }
  223.         }
  224.         $definitions->ksort();
  225.         $paths->ksort();
  226.         return $this->computeDoc($v3$object$definitions$paths$context);
  227.     }
  228.     /**
  229.      * Updates the list of entries in the paths collection.
  230.      */
  231.     private function addPaths(bool $v3\ArrayObject $paths\ArrayObject $definitionsstring $resourceClassstring $resourceShortNameResourceMetadata $resourceMetadatastring $operationType\ArrayObject $links)
  232.     {
  233.         if (null === $operations OperationType::COLLECTION === $operationType $resourceMetadata->getCollectionOperations() : $resourceMetadata->getItemOperations()) {
  234.             return;
  235.         }
  236.         foreach ($operations as $operationName => $operation) {
  237.             // Skolem IRI
  238.             if ('api_genid' === ($operation['route_name'] ?? null)) {
  239.                 continue;
  240.             }
  241.             if (isset($operation['uri_template'])) {
  242.                 $path str_replace('.{_format}'''$operation['uri_template']);
  243.                 if (!== strpos($path'/')) {
  244.                     $path '/'.$path;
  245.                 }
  246.             } else {
  247.                 $path $this->getPath($resourceShortName$operationName$operation$operationType);
  248.             }
  249.             if ($this->operationMethodResolver) {
  250.                 $method OperationType::ITEM === $operationType $this->operationMethodResolver->getItemOperationMethod($resourceClass$operationName) : $this->operationMethodResolver->getCollectionOperationMethod($resourceClass$operationName);
  251.             } else {
  252.                 $method $resourceMetadata->getTypedOperationAttribute($operationType$operationName'method''GET');
  253.             }
  254.             $paths[$path][strtolower($method)] = $this->getPathOperation($v3$operationName$operation$method$operationType$resourceClass$resourceMetadata$definitions$links);
  255.         }
  256.     }
  257.     /**
  258.      * Gets the path for an operation.
  259.      *
  260.      * If the path ends with the optional _format parameter, it is removed
  261.      * as optional path parameters are not yet supported.
  262.      *
  263.      * @see https://github.com/OAI/OpenAPI-Specification/issues/93
  264.      */
  265.     private function getPath(string $resourceShortNamestring $operationName, array $operationstring $operationType): string
  266.     {
  267.         $path $this->operationPathResolver->resolveOperationPath($resourceShortName$operation$operationType$operationName);
  268.         if ('.{_format}' === substr($path, -10)) {
  269.             $path substr($path0, -10);
  270.         }
  271.         return $path;
  272.     }
  273.     /**
  274.      * Gets a path Operation Object.
  275.      *
  276.      * @see https://github.com/OAI/OpenAPI-Specification/blob/master/versions/2.0.md#operation-object
  277.      */
  278.     private function getPathOperation(bool $v3string $operationName, array $operationstring $methodstring $operationTypestring $resourceClassResourceMetadata $resourceMetadata\ArrayObject $definitions\ArrayObject $links): \ArrayObject
  279.     {
  280.         $pathOperation = new \ArrayObject($operation[$v3 'openapi_context' 'swagger_context'] ?? []);
  281.         $resourceShortName $resourceMetadata->getShortName();
  282.         $pathOperation['tags'] ?? $pathOperation['tags'] = [$resourceShortName];
  283.         $pathOperation['operationId'] ?? $pathOperation['operationId'] = lcfirst($operationName).ucfirst($resourceShortName).ucfirst($operationType);
  284.         if ($v3 && 'GET' === $method && OperationType::ITEM === $operationType && $link $this->getLinkObject($resourceClass$pathOperation['operationId'], $this->getPath($resourceShortName$operationName$operation$operationType))) {
  285.             $links[$pathOperation['operationId']] = $link;
  286.         }
  287.         if ($resourceMetadata->getTypedOperationAttribute($operationType$operationName'deprecation_reason'nulltrue)) {
  288.             $pathOperation['deprecated'] = true;
  289.         }
  290.         if (null === $this->formatsProvider) {
  291.             $requestFormats $resourceMetadata->getTypedOperationAttribute($operationType$operationName'input_formats', [], true);
  292.             $responseFormats $resourceMetadata->getTypedOperationAttribute($operationType$operationName'output_formats', [], true);
  293.         } else {
  294.             $requestFormats $responseFormats $this->formatsProvider->getFormatsFromOperation($resourceClass$operationName$operationType);
  295.         }
  296.         $requestMimeTypes $this->flattenMimeTypes($requestFormats);
  297.         $responseMimeTypes $this->flattenMimeTypes($responseFormats);
  298.         switch ($method) {
  299.             case 'GET':
  300.                 return $this->updateGetOperation($v3$pathOperation$responseMimeTypes$operationType$resourceMetadata$resourceClass$resourceShortName$operationName$definitions);
  301.             case 'POST':
  302.                 return $this->updatePostOperation($v3$pathOperation$requestMimeTypes$responseMimeTypes$operationType$resourceMetadata$resourceClass$resourceShortName$operationName$definitions$links);
  303.             case 'PATCH':
  304.                 $pathOperation['summary'] ?? $pathOperation['summary'] = sprintf('Updates the %s resource.'$resourceShortName);
  305.                 // no break
  306.             case 'PUT':
  307.                 return $this->updatePutOperation($v3$pathOperation$requestMimeTypes$responseMimeTypes$operationType$resourceMetadata$resourceClass$resourceShortName$operationName$definitions);
  308.             case 'DELETE':
  309.                 return $this->updateDeleteOperation($v3$pathOperation$resourceShortName$operationType$operationName$resourceMetadata$resourceClass);
  310.         }
  311.         return $pathOperation;
  312.     }
  313.     /**
  314.      * @return array the update message as first value, and if the schema is defined as second
  315.      */
  316.     private function addSchemas(bool $v3, array $message\ArrayObject $definitionsstring $resourceClassstring $operationTypestring $operationName, array $mimeTypesstring $type Schema::TYPE_OUTPUTbool $forceCollection false): array
  317.     {
  318.         if (!$v3) {
  319.             $jsonSchema $this->getJsonSchema($v3$definitions$resourceClass$type$operationType$operationName'json'null$forceCollection);
  320.             if (!$jsonSchema->isDefined()) {
  321.                 return [$messagefalse];
  322.             }
  323.             $message['schema'] = $jsonSchema->getArrayCopy(false);
  324.             return [$messagetrue];
  325.         }
  326.         foreach ($mimeTypes as $mimeType => $format) {
  327.             $jsonSchema $this->getJsonSchema($v3$definitions$resourceClass$type$operationType$operationName$formatnull$forceCollection);
  328.             if (!$jsonSchema->isDefined()) {
  329.                 return [$messagefalse];
  330.             }
  331.             $message['content'][$mimeType] = ['schema' => $jsonSchema->getArrayCopy(false)];
  332.         }
  333.         return [$messagetrue];
  334.     }
  335.     private function updateGetOperation(bool $v3\ArrayObject $pathOperation, array $mimeTypesstring $operationTypeResourceMetadata $resourceMetadatastring $resourceClassstring $resourceShortNamestring $operationName\ArrayObject $definitions): \ArrayObject
  336.     {
  337.         $successStatus = (string) $resourceMetadata->getTypedOperationAttribute($operationType$operationName'status''200');
  338.         if (!$v3) {
  339.             $pathOperation['produces'] ?? $pathOperation['produces'] = array_keys($mimeTypes);
  340.         }
  341.         if (OperationType::COLLECTION === $operationType) {
  342.             $outputResourseShortName $resourceMetadata->getCollectionOperations()[$operationName]['output']['name'] ?? $resourceShortName;
  343.             $pathOperation['summary'] ?? $pathOperation['summary'] = sprintf('Retrieves the collection of %s resources.'$outputResourseShortName);
  344.             $successResponse = ['description' => sprintf('%s collection response'$outputResourseShortName)];
  345.             [$successResponse] = $this->addSchemas($v3$successResponse$definitions$resourceClass$operationType$operationName$mimeTypes);
  346.             $pathOperation['responses'] ?? $pathOperation['responses'] = [$successStatus => $successResponse];
  347.             if (
  348.                 ($resourceMetadata->getAttributes()['extra_properties']['is_legacy_subresource'] ?? false) ||
  349.                 ($resourceMetadata->getAttributes()['extra_properties']['is_alternate_resource_metadata'] ?? false)) {
  350.                 // Avoid duplicates parameters when there is a filter on a subresource identifier
  351.                 $parametersMemory = [];
  352.                 $pathOperation['parameters'] = [];
  353.                 foreach ($resourceMetadata->getCollectionOperations()[$operationName]['identifiers'] as $parameterName => [$class$identifier]) {
  354.                     $parameter = ['name' => $parameterName'in' => 'path''required' => true];
  355.                     $v3 $parameter['schema'] = ['type' => 'string'] : $parameter['type'] = 'string';
  356.                     $pathOperation['parameters'][] = $parameter;
  357.                     $parametersMemory[] = $parameterName;
  358.                 }
  359.                 if ($parameters $this->getFiltersParameters($v3$resourceClass$operationName$resourceMetadata)) {
  360.                     foreach ($parameters as $parameter) {
  361.                         if (!\in_array($parameter['name'], $parametersMemorytrue)) {
  362.                             $pathOperation['parameters'][] = $parameter;
  363.                         }
  364.                     }
  365.                 }
  366.             } else {
  367.                 $pathOperation['parameters'] ?? $pathOperation['parameters'] = $this->getFiltersParameters($v3$resourceClass$operationName$resourceMetadata);
  368.             }
  369.             $this->addPaginationParameters($v3$resourceMetadataOperationType::COLLECTION$operationName$pathOperation);
  370.             return $pathOperation;
  371.         }
  372.         $outputResourseShortName $resourceMetadata->getItemOperations()[$operationName]['output']['name'] ?? $resourceShortName;
  373.         $pathOperation['summary'] ?? $pathOperation['summary'] = sprintf('Retrieves a %s resource.'$outputResourseShortName);
  374.         $pathOperation $this->addItemOperationParameters($v3$pathOperation$operationType$operationName$resourceMetadata$resourceClass);
  375.         $successResponse = ['description' => sprintf('%s resource response'$outputResourseShortName)];
  376.         [$successResponse] = $this->addSchemas($v3$successResponse$definitions$resourceClass$operationType$operationName$mimeTypes);
  377.         $pathOperation['responses'] ?? $pathOperation['responses'] = [
  378.             $successStatus => $successResponse,
  379.             '404' => ['description' => 'Resource not found'],
  380.         ];
  381.         return $pathOperation;
  382.     }
  383.     private function addPaginationParameters(bool $v3ResourceMetadata $resourceMetadatastring $operationTypestring $operationName\ArrayObject $pathOperation)
  384.     {
  385.         if ($this->paginationEnabled && $resourceMetadata->getTypedOperationAttribute($operationType$operationName'pagination_enabled'truetrue)) {
  386.             $paginationParameter = [
  387.                 'name' => $this->paginationPageParameterName,
  388.                 'in' => 'query',
  389.                 'required' => false,
  390.                 'description' => 'The collection page number',
  391.             ];
  392.             $v3 $paginationParameter['schema'] = [
  393.                 'type' => 'integer',
  394.                 'default' => 1,
  395.             ] : $paginationParameter['type'] = 'integer';
  396.             $pathOperation['parameters'][] = $paginationParameter;
  397.             if ($resourceMetadata->getTypedOperationAttribute($operationType$operationName'pagination_client_items_per_page'$this->clientItemsPerPagetrue)) {
  398.                 $itemPerPageParameter = [
  399.                     'name' => $this->itemsPerPageParameterName,
  400.                     'in' => 'query',
  401.                     'required' => false,
  402.                     'description' => 'The number of items per page',
  403.                 ];
  404.                 if ($v3) {
  405.                     $itemPerPageParameter['schema'] = [
  406.                         'type' => 'integer',
  407.                         'default' => $resourceMetadata->getTypedOperationAttribute($operationType$operationName'pagination_items_per_page'30true),
  408.                         'minimum' => 0,
  409.                     ];
  410.                     $maxItemsPerPage $resourceMetadata->getTypedOperationAttribute($operationType$operationName'maximum_items_per_page'nulltrue);
  411.                     if (null !== $maxItemsPerPage) {
  412.                         @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);
  413.                     }
  414.                     $maxItemsPerPage $resourceMetadata->getTypedOperationAttribute($operationType$operationName'pagination_maximum_items_per_page'$maxItemsPerPagetrue);
  415.                     if (null !== $maxItemsPerPage) {
  416.                         $itemPerPageParameter['schema']['maximum'] = $maxItemsPerPage;
  417.                     }
  418.                 } else {
  419.                     $itemPerPageParameter['type'] = 'integer';
  420.                 }
  421.                 $pathOperation['parameters'][] = $itemPerPageParameter;
  422.             }
  423.         }
  424.         if ($this->paginationEnabled && $resourceMetadata->getTypedOperationAttribute($operationType$operationName'pagination_client_enabled'$this->paginationClientEnabledtrue)) {
  425.             $paginationEnabledParameter = [
  426.                 'name' => $this->paginationClientEnabledParameterName,
  427.                 'in' => 'query',
  428.                 'required' => false,
  429.                 'description' => 'Enable or disable pagination',
  430.             ];
  431.             $v3 $paginationEnabledParameter['schema'] = ['type' => 'boolean'] : $paginationEnabledParameter['type'] = 'boolean';
  432.             $pathOperation['parameters'][] = $paginationEnabledParameter;
  433.         }
  434.     }
  435.     /**
  436.      * @throws ResourceClassNotFoundException
  437.      */
  438.     private function addSubresourceOperation(bool $v3, array $subresourceOperation\ArrayObject $definitionsstring $operationIdResourceMetadata $resourceMetadata): \ArrayObject
  439.     {
  440.         $operationName 'get'// TODO: we might want to extract that at some point to also support other subresource operations
  441.         $collection $subresourceOperation['collection'] ?? false;
  442.         $subResourceMetadata $this->resourceMetadataFactory->create($subresourceOperation['resource_class']);
  443.         $pathOperation = new \ArrayObject([]);
  444.         $pathOperation['tags'] = $subresourceOperation['shortNames'];
  445.         $pathOperation['operationId'] = $operationId;
  446.         $pathOperation['summary'] = sprintf('Retrieves %s%s resource%s.'$subresourceOperation['collection'] ? 'the collection of ' 'a '$subresourceOperation['shortNames'][0], $subresourceOperation['collection'] ? 's' '');
  447.         if (null === $this->formatsProvider) {
  448.             // TODO: Subresource operation metadata aren't available by default, for now we have to fallback on default formats.
  449.             // TODO: A better approach would be to always populate the subresource operation array.
  450.             $subResourceMetadata $this
  451.                 ->resourceMetadataFactory
  452.                 ->create($subresourceOperation['resource_class']);
  453.             if ($this->resourceMetadataFactory instanceof ResourceMetadataCollectionFactoryInterface) {
  454.                 $subResourceMetadata $this->transformResourceToResourceMetadata($subResourceMetadata[0]);
  455.             }
  456.             $responseFormats $subResourceMetadata->getTypedOperationAttribute(OperationType::SUBRESOURCE$operationName'output_formats'$this->formatstrue);
  457.         } else {
  458.             $responseFormats $this->formatsProvider->getFormatsFromOperation($subresourceOperation['resource_class'], $operationNameOperationType::SUBRESOURCE);
  459.         }
  460.         $mimeTypes $this->flattenMimeTypes($responseFormats);
  461.         if (!$v3) {
  462.             $pathOperation['produces'] = array_keys($mimeTypes);
  463.         }
  464.         $successResponse = [
  465.             'description' => sprintf('%s %s response'$subresourceOperation['shortNames'][0], $collection 'collection' 'resource'),
  466.         ];
  467.         [$successResponse] = $this->addSchemas($v3$successResponse$definitions$subresourceOperation['resource_class'], OperationType::SUBRESOURCE$operationName$mimeTypesSchema::TYPE_OUTPUT$collection);
  468.         $pathOperation['responses'] = ['200' => $successResponse'404' => ['description' => 'Resource not found']];
  469.         // Avoid duplicates parameters when there is a filter on a subresource identifier
  470.         $parametersMemory = [];
  471.         $pathOperation['parameters'] = [];
  472.         foreach ($subresourceOperation['identifiers'] as $parameterName => [$class$identifier$hasIdentifier]) {
  473.             if (false === strpos($subresourceOperation['path'], sprintf('{%s}'$parameterName))) {
  474.                 continue;
  475.             }
  476.             $parameter = ['name' => $parameterName'in' => 'path''required' => true];
  477.             $v3 $parameter['schema'] = ['type' => 'string'] : $parameter['type'] = 'string';
  478.             $pathOperation['parameters'][] = $parameter;
  479.             $parametersMemory[] = $parameterName;
  480.         }
  481.         if ($parameters $this->getFiltersParameters($v3$subresourceOperation['resource_class'], $operationName$subResourceMetadata)) {
  482.             foreach ($parameters as $parameter) {
  483.                 if (!\in_array($parameter['name'], $parametersMemorytrue)) {
  484.                     $pathOperation['parameters'][] = $parameter;
  485.                 }
  486.             }
  487.         }
  488.         if ($subresourceOperation['collection']) {
  489.             $this->addPaginationParameters($v3$subResourceMetadataOperationType::SUBRESOURCE$subresourceOperation['operation_name'], $pathOperation);
  490.         }
  491.         return $pathOperation;
  492.     }
  493.     private function updatePostOperation(bool $v3\ArrayObject $pathOperation, array $requestMimeTypes, array $responseMimeTypesstring $operationTypeResourceMetadata $resourceMetadatastring $resourceClassstring $resourceShortNamestring $operationName\ArrayObject $definitions\ArrayObject $links): \ArrayObject
  494.     {
  495.         if (!$v3) {
  496.             $pathOperation['consumes'] ?? $pathOperation['consumes'] = array_keys($requestMimeTypes);
  497.             $pathOperation['produces'] ?? $pathOperation['produces'] = array_keys($responseMimeTypes);
  498.         }
  499.         $pathOperation['summary'] ?? $pathOperation['summary'] = sprintf('Creates a %s resource.'$resourceShortName);
  500.         $identifiers = (array) $resourceMetadata
  501.                 ->getTypedOperationAttribute($operationType$operationName'identifiers', [], false);
  502.         $pathOperation $this->addItemOperationParameters($v3$pathOperation$operationType$operationName$resourceMetadata$resourceClassOperationType::ITEM === $operationType false true);
  503.         $successResponse = ['description' => sprintf('%s resource created'$resourceShortName)];
  504.         [$successResponse$defined] = $this->addSchemas($v3$successResponse$definitions$resourceClass$operationType$operationName$responseMimeTypes);
  505.         if ($defined && $v3 && ($links[$key 'get'.ucfirst($resourceShortName).ucfirst(OperationType::ITEM)] ?? null)) {
  506.             $successResponse['links'] = [ucfirst($key) => $links[$key]];
  507.         }
  508.         $pathOperation['responses'] ?? $pathOperation['responses'] = [
  509.             (string) $resourceMetadata->getTypedOperationAttribute($operationType$operationName'status''201') => $successResponse,
  510.             '400' => ['description' => 'Invalid input'],
  511.             '404' => ['description' => 'Resource not found'],
  512.             '422' => ['description' => 'Unprocessable entity'],
  513.         ];
  514.         return $this->addRequestBody($v3$pathOperation$definitions$resourceClass$resourceShortName$operationType$operationName$requestMimeTypes);
  515.     }
  516.     private function updatePutOperation(bool $v3\ArrayObject $pathOperation, array $requestMimeTypes, array $responseMimeTypesstring $operationTypeResourceMetadata $resourceMetadatastring $resourceClassstring $resourceShortNamestring $operationName\ArrayObject $definitions): \ArrayObject
  517.     {
  518.         if (!$v3) {
  519.             $pathOperation['consumes'] ?? $pathOperation['consumes'] = array_keys($requestMimeTypes);
  520.             $pathOperation['produces'] ?? $pathOperation['produces'] = array_keys($responseMimeTypes);
  521.         }
  522.         $pathOperation['summary'] ?? $pathOperation['summary'] = sprintf('Replaces the %s resource.'$resourceShortName);
  523.         $pathOperation $this->addItemOperationParameters($v3$pathOperation$operationType$operationName$resourceMetadata$resourceClass);
  524.         $successResponse = ['description' => sprintf('%s resource updated'$resourceShortName)];
  525.         [$successResponse] = $this->addSchemas($v3$successResponse$definitions$resourceClass$operationType$operationName$responseMimeTypes);
  526.         $pathOperation['responses'] ?? $pathOperation['responses'] = [
  527.             (string) $resourceMetadata->getTypedOperationAttribute($operationType$operationName'status''200') => $successResponse,
  528.             '400' => ['description' => 'Invalid input'],
  529.             '404' => ['description' => 'Resource not found'],
  530.             '422' => ['description' => 'Unprocessable entity'],
  531.         ];
  532.         return $this->addRequestBody($v3$pathOperation$definitions$resourceClass$resourceShortName$operationType$operationName$requestMimeTypestrue);
  533.     }
  534.     private function addRequestBody(bool $v3\ArrayObject $pathOperation\ArrayObject $definitionsstring $resourceClassstring $resourceShortNamestring $operationTypestring $operationName, array $requestMimeTypesbool $put false)
  535.     {
  536.         if (isset($pathOperation['requestBody'])) {
  537.             return $pathOperation;
  538.         }
  539.         [$message$defined] = $this->addSchemas($v3, [], $definitions$resourceClass$operationType$operationName$requestMimeTypesSchema::TYPE_INPUT);
  540.         if (!$defined) {
  541.             return $pathOperation;
  542.         }
  543.         $description sprintf('The %s %s resource'$put 'updated' 'new'$resourceShortName);
  544.         if ($v3) {
  545.             $pathOperation['requestBody'] = $message + ['description' => $description];
  546.             return $pathOperation;
  547.         }
  548.         if (!$this->hasBodyParameter($pathOperation['parameters'] ?? [])) {
  549.             $pathOperation['parameters'][] = [
  550.                 'name' => lcfirst($resourceShortName),
  551.                 'in' => 'body',
  552.                 'description' => $description,
  553.             ] + $message;
  554.         }
  555.         return $pathOperation;
  556.     }
  557.     private function hasBodyParameter(array $parameters): bool
  558.     {
  559.         foreach ($parameters as $parameter) {
  560.             if (\array_key_exists('in'$parameter) && 'body' === $parameter['in']) {
  561.                 return true;
  562.             }
  563.         }
  564.         return false;
  565.     }
  566.     private function updateDeleteOperation(bool $v3\ArrayObject $pathOperationstring $resourceShortNamestring $operationTypestring $operationNameResourceMetadata $resourceMetadatastring $resourceClass): \ArrayObject
  567.     {
  568.         $pathOperation['summary'] ?? $pathOperation['summary'] = sprintf('Removes the %s resource.'$resourceShortName);
  569.         $pathOperation['responses'] ?? $pathOperation['responses'] = [
  570.             (string) $resourceMetadata->getTypedOperationAttribute($operationType$operationName'status''204') => ['description' => sprintf('%s resource deleted'$resourceShortName)],
  571.             '404' => ['description' => 'Resource not found'],
  572.         ];
  573.         return $this->addItemOperationParameters($v3$pathOperation$operationType$operationName$resourceMetadata$resourceClass);
  574.     }
  575.     private function addItemOperationParameters(bool $v3\ArrayObject $pathOperationstring $operationTypestring $operationNameResourceMetadata $resourceMetadatastring $resourceClassbool $isPost false): \ArrayObject
  576.     {
  577.         $identifiers = (array) $resourceMetadata
  578.                 ->getTypedOperationAttribute($operationType$operationName'identifiers', [], false);
  579.         // Auto-generated routes in API Platform < 2.7 are considered as collection, hotfix this as the OpenApi Factory supports new operations anyways.
  580.         // this also fixes a bug where we could not create POST item operations in API P 2.6
  581.         if (OperationType::ITEM === $operationType && $isPost) {
  582.             $operationType OperationType::COLLECTION;
  583.         }
  584.         if (!$identifiers && OperationType::COLLECTION !== $operationType) {
  585.             try {
  586.                 $identifiers $this->identifiersExtractor->getIdentifiersFromResourceClass($resourceClass);
  587.             } catch (RuntimeException $e) {
  588.                 // Ignore exception here
  589.             } catch (ResourceClassNotFoundException $e) {
  590.                 if (false === $this->legacyMode) {
  591.                     // Skipping these, swagger is not compatible with post 2.7 resource metadata
  592.                     return $pathOperation;
  593.                 }
  594.                 throw $e;
  595.             }
  596.         }
  597.         if (\count($identifiers) > $resourceMetadata->getItemOperationAttribute($operationName'composite_identifier'truetrue) : false) {
  598.             $identifiers = ['id'];
  599.         }
  600.         if (!$identifiers && OperationType::COLLECTION === $operationType) {
  601.             return $pathOperation;
  602.         }
  603.         if (!isset($pathOperation['parameters'])) {
  604.             $pathOperation['parameters'] = [];
  605.         }
  606.         foreach ($identifiers as $parameterName => $identifier) {
  607.             $parameter = [
  608.                 'name' => \is_string($parameterName) ? $parameterName $identifier,
  609.                 'in' => 'path',
  610.                 'required' => true,
  611.             ];
  612.             $v3 $parameter['schema'] = ['type' => 'string'] : $parameter['type'] = 'string';
  613.             $pathOperation['parameters'][] = $parameter;
  614.         }
  615.         return $pathOperation;
  616.     }
  617.     private function getJsonSchema(bool $v3\ArrayObject $definitionsstring $resourceClassstring $type, ?string $operationType, ?string $operationNamestring $format 'json', ?array $serializerContext nullbool $forceCollection false): Schema
  618.     {
  619.         $schema = new Schema($v3 Schema::VERSION_OPENAPI Schema::VERSION_SWAGGER);
  620.         $schema->setDefinitions($definitions);
  621.         if ($this->jsonSchemaFactory instanceof SchemaFactoryInterface) {
  622.             $operation $operationName ? (new class() extends HttpOperation {})->withName($operationName) : null;
  623.             return $this->jsonSchemaFactory->buildSchema($resourceClass$format$type$operation$schema$serializerContext$forceCollection);
  624.         }
  625.         return $this->jsonSchemaFactory->buildSchema($resourceClass$format$type$operationType$operationName$schema$serializerContext$forceCollection);
  626.     }
  627.     private function computeDoc(bool $v3Documentation $documentation\ArrayObject $definitions\ArrayObject $paths, array $context): array
  628.     {
  629.         $baseUrl $context[self::BASE_URL] ?? $this->defaultContext[self::BASE_URL];
  630.         if ($v3) {
  631.             $docs = ['openapi' => self::OPENAPI_VERSION];
  632.             if ('/' !== $baseUrl && '' !== $baseUrl) {
  633.                 $docs['servers'] = [['url' => $baseUrl]];
  634.             }
  635.         } else {
  636.             $docs = [
  637.                 'swagger' => self::SWAGGER_VERSION,
  638.                 'basePath' => $baseUrl,
  639.             ];
  640.         }
  641.         $docs += [
  642.             'info' => [
  643.                 'title' => $documentation->getTitle(),
  644.                 'version' => $documentation->getVersion(),
  645.             ],
  646.             'paths' => $paths,
  647.         ];
  648.         if ('' !== $description $documentation->getDescription()) {
  649.             $docs['info']['description'] = $description;
  650.         }
  651.         $securityDefinitions = [];
  652.         $security = [];
  653.         if ($this->oauthEnabled) {
  654.             $oauthAttributes = [
  655.                 'authorizationUrl' => $this->oauthAuthorizationUrl,
  656.                 'scopes' => new \ArrayObject($this->oauthScopes),
  657.             ];
  658.             if ($this->oauthTokenUrl) {
  659.                 $oauthAttributes['tokenUrl'] = $this->oauthTokenUrl;
  660.             }
  661.             $securityDefinitions['oauth'] = [
  662.                 'type' => $this->oauthType,
  663.                 'description' => sprintf(
  664.                     'OAuth 2.0 %s Grant',
  665.                     strtolower(preg_replace('/[A-Z]/'' \\0'lcfirst($this->oauthFlow)))
  666.                 ),
  667.             ];
  668.             if ($v3) {
  669.                 $securityDefinitions['oauth']['flows'] = [
  670.                     $this->oauthFlow => $oauthAttributes,
  671.                 ];
  672.             } else {
  673.                 $securityDefinitions['oauth']['flow'] = $this->oauthFlow;
  674.                 $securityDefinitions['oauth'] = array_merge($securityDefinitions['oauth'], $oauthAttributes);
  675.             }
  676.             $security[] = ['oauth' => []];
  677.         }
  678.         foreach ($this->apiKeys as $key => $apiKey) {
  679.             $name $apiKey['name'];
  680.             $type $apiKey['type'];
  681.             $securityDefinitions[$key] = [
  682.                 'type' => 'apiKey',
  683.                 'in' => $type,
  684.                 'description' => sprintf('Value for the %s %s'$name'query' === $type sprintf('%s parameter'$type) : $type),
  685.                 'name' => $name,
  686.             ];
  687.             $security[] = [$key => []];
  688.         }
  689.         if ($securityDefinitions && $security) { // @phpstan-ignore-line false positive
  690.             $docs['security'] = $security;
  691.             if (!$v3) {
  692.                 $docs['securityDefinitions'] = $securityDefinitions;
  693.             }
  694.         }
  695.         if ($v3) {
  696.             if (\count($definitions) + \count($securityDefinitions)) {
  697.                 $docs['components'] = [];
  698.                 if (\count($definitions)) {
  699.                     $docs['components']['schemas'] = $definitions;
  700.                 }
  701.                 if (\count($securityDefinitions)) {
  702.                     $docs['components']['securitySchemes'] = $securityDefinitions;
  703.                 }
  704.             }
  705.         } elseif (\count($definitions) > 0) {
  706.             $docs['definitions'] = $definitions;
  707.         }
  708.         return $docs;
  709.     }
  710.     /**
  711.      * Gets parameters corresponding to enabled filters.
  712.      */
  713.     private function getFiltersParameters(bool $v3string $resourceClassstring $operationNameResourceMetadata $resourceMetadata): array
  714.     {
  715.         if (null === $this->filterLocator) {
  716.             return [];
  717.         }
  718.         $parameters = [];
  719.         $resourceFilters $resourceMetadata->getCollectionOperationAttribute($operationName'filters', [], true);
  720.         foreach ($resourceFilters as $filterId) {
  721.             if (!$filter $this->getFilter($filterId)) {
  722.                 continue;
  723.             }
  724.             foreach ($filter->getDescription($resourceClass) as $name => $data) {
  725.                 $parameter = [
  726.                     'name' => $name,
  727.                     'in' => 'query',
  728.                     'required' => $data['required'],
  729.                 ];
  730.                 $type \in_array($data['type'], Type::$builtinTypestrue) ? $this->jsonSchemaTypeFactory->getType(new Type($data['type'], falsenull$data['is_collection'] ?? false)) : ['type' => 'string'];
  731.                 $v3 $parameter['schema'] = $type $parameter += $type;
  732.                 if ($v3 && isset($data['schema'])) {
  733.                     $parameter['schema'] = $data['schema'];
  734.                 }
  735.                 if ('array' === ($type['type'] ?? '')) {
  736.                     $deepObject \in_array($data['type'], [Type::BUILTIN_TYPE_ARRAYType::BUILTIN_TYPE_OBJECT], true);
  737.                     if ($v3) {
  738.                         $parameter['style'] = $deepObject 'deepObject' 'form';
  739.                         $parameter['explode'] = true;
  740.                     } else {
  741.                         $parameter['collectionFormat'] = $deepObject 'csv' 'multi';
  742.                     }
  743.                 }
  744.                 $key $v3 'openapi' 'swagger';
  745.                 if (isset($data[$key])) {
  746.                     $parameter $data[$key] + $parameter;
  747.                 }
  748.                 $parameters[] = $parameter;
  749.             }
  750.         }
  751.         return $parameters;
  752.     }
  753.     /**
  754.      * {@inheritdoc}
  755.      */
  756.     public function supportsNormalization($data$format null, array $context = []): bool
  757.     {
  758.         return self::FORMAT === $format && ($data instanceof Documentation || $this->openApiNormalizer && $data instanceof OpenApi);
  759.     }
  760.     /**
  761.      * {@inheritdoc}
  762.      */
  763.     public function hasCacheableSupportsMethod(): bool
  764.     {
  765.         return true;
  766.     }
  767.     private function flattenMimeTypes(array $responseFormats): array
  768.     {
  769.         $responseMimeTypes = [];
  770.         foreach ($responseFormats as $responseFormat => $mimeTypes) {
  771.             foreach ($mimeTypes as $mimeType) {
  772.                 $responseMimeTypes[$mimeType] = $responseFormat;
  773.             }
  774.         }
  775.         return $responseMimeTypes;
  776.     }
  777.     /**
  778.      * https://github.com/OAI/OpenAPI-Specification/blob/master/versions/3.0.0.md#linkObject.
  779.      */
  780.     private function getLinkObject(string $resourceClassstring $operationIdstring $path): array
  781.     {
  782.         $linkObject $identifiers = [];
  783.         foreach ($this->propertyNameCollectionFactory->create($resourceClass) as $propertyName) {
  784.             $propertyMetadata $this->propertyMetadataFactory->create($resourceClass$propertyName);
  785.             if (!$propertyMetadata->isIdentifier()) {
  786.                 continue;
  787.             }
  788.             $linkObject['parameters'][$propertyName] = sprintf('$response.body#/%s'$propertyName);
  789.             $identifiers[] = $propertyName;
  790.         }
  791.         if (!$linkObject) {
  792.             return [];
  793.         }
  794.         $linkObject['operationId'] = $operationId;
  795.         $linkObject['description'] = === \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);
  796.         return $linkObject;
  797.     }
  798. }