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

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