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

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