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

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