vendor/api-platform/core/src/Core/JsonSchema/SchemaFactory.php line 61

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\JsonSchema;
  16. use ApiPlatform\Api\ResourceClassResolverInterface;
  17. use ApiPlatform\Core\Api\OperationType;
  18. use ApiPlatform\Core\Metadata\Property\Factory\PropertyMetadataFactoryInterface as LegacyPropertyMetadataFactoryInterface;
  19. use ApiPlatform\Core\Metadata\Property\Factory\PropertyNameCollectionFactoryInterface as LegacyPropertyNameCollectionFactoryInterface;
  20. use ApiPlatform\Core\Metadata\Property\PropertyMetadata;
  21. use ApiPlatform\Core\Metadata\Resource\Factory\ResourceMetadataFactoryInterface;
  22. use ApiPlatform\Core\Metadata\Resource\ResourceMetadata;
  23. use ApiPlatform\Core\Swagger\Serializer\DocumentationNormalizer;
  24. use ApiPlatform\JsonSchema\TypeFactoryInterface;
  25. use ApiPlatform\Metadata\ApiProperty;
  26. use ApiPlatform\Metadata\HttpOperation;
  27. use ApiPlatform\Metadata\Property\Factory\PropertyMetadataFactoryInterface;
  28. use ApiPlatform\Metadata\Property\Factory\PropertyNameCollectionFactoryInterface;
  29. use ApiPlatform\Metadata\Resource\Factory\ResourceMetadataCollectionFactoryInterface;
  30. use ApiPlatform\Metadata\Resource\ResourceMetadataCollection;
  31. use ApiPlatform\OpenApi\Factory\OpenApiFactory;
  32. use ApiPlatform\Util\ResourceClassInfoTrait;
  33. use Symfony\Component\PropertyInfo\Type;
  34. use Symfony\Component\Serializer\NameConverter\NameConverterInterface;
  35. use Symfony\Component\Serializer\Normalizer\AbstractNormalizer;
  37. /**
  38. * @experimental
  39. *
  40. * @author Kévin Dunglas <dunglas@gmail.com>
  41. */
  42. final class SchemaFactory implements SchemaFactoryInterface
  43. {
  44. use ResourceClassInfoTrait;
  46. private $typeFactory;
  47. /**
  48. * @var LegacyPropertyNameCollectionFactoryInterface|PropertyNameCollectionFactoryInterface
  49. */
  50. private $propertyNameCollectionFactory;
  51. /**
  52. * @var LegacyPropertyMetadataFactoryInterface|PropertyMetadataFactoryInterface
  53. */
  54. private $propertyMetadataFactory;
  55. private $nameConverter;
  56. private $distinctFormats = [];
  58. /**
  59. * @param TypeFactoryInterface $typeFactory
  60. */
  61. public function __construct($typeFactory, $resourceMetadataFactory, $propertyNameCollectionFactory, $propertyMetadataFactory, NameConverterInterface $nameConverter = null, ResourceClassResolverInterface $resourceClassResolver = null)
  62. {
  63. $this->typeFactory = $typeFactory;
  64. if (!$resourceMetadataFactory instanceof ResourceMetadataCollectionFactoryInterface) {
  65. trigger_deprecation('api-platform/core', '2.7', sprintf('Use "%s" instead of "%s".', ResourceMetadataCollectionFactoryInterface::class, ResourceMetadataFactoryInterface::class));
  66. }
  67. $this->resourceMetadataFactory = $resourceMetadataFactory;
  68. $this->propertyNameCollectionFactory = $propertyNameCollectionFactory;
  69. $this->propertyMetadataFactory = $propertyMetadataFactory;
  70. $this->nameConverter = $nameConverter;
  71. $this->resourceClassResolver = $resourceClassResolver;
  72. }
  74. /**
  75. * When added to the list, the given format will lead to the creation of a new definition.
  76. *
  77. * @internal
  78. */
  79. public function addDistinctFormat(string $format): void
  80. {
  81. $this->distinctFormats[$format] = true;
  82. }
  84. public function buildSchema(string $className, string $format = 'json', string $type = Schema::TYPE_OUTPUT, string $operationType = null, string $operationName = null, Schema $schema = null, array $serializerContext = null, bool $forceCollection = false): Schema
  85. {
  86. $schema = $schema ? clone $schema : new Schema();
  87. if (null === $metadata = $this->getMetadata($className, $type, $operationType, $operationName, $serializerContext)) {
  88. return $schema;
  89. }
  91. [$resourceMetadata, $serializerContext, $validationGroups, $inputOrOutputClass] = $metadata;
  93. if (null === $resourceMetadata && (null !== $operationType || null !== $operationName)) {
  94. throw new \LogicException('The $operationType and $operationName arguments must be null for non-resource class.');
  95. }
  97. $operation = $resourceMetadata instanceof ResourceMetadataCollection ? $resourceMetadata->getOperation($operationName, OperationType::COLLECTION === $operationType) : null;
  99. $version = $schema->getVersion();
  100. $definitionName = $this->buildDefinitionName($className, $format, $inputOrOutputClass, $resourceMetadata instanceof ResourceMetadata ? $resourceMetadata : $operation, $serializerContext);
  102. $method = $operation instanceof HttpOperation ? $operation->getMethod() : 'GET';
  103. if (!$operation && (null === $operationType || null === $operationName)) {
  104. $method = Schema::TYPE_INPUT === $type ? 'POST' : 'GET';
  105. } elseif ($resourceMetadata instanceof ResourceMetadata) {
  106. $method = $resourceMetadata->getTypedOperationAttribute($operationType, $operationName, 'method', 'GET');
  107. }
  109. if (Schema::TYPE_OUTPUT !== $type && !\in_array($method, ['POST', 'PATCH', 'PUT'], true)) {
  110. return $schema;
  111. }
  113. if (!isset($schema['$ref']) && !isset($schema['type'])) {
  114. $ref = Schema::VERSION_OPENAPI === $version ? '#/components/schemas/'.$definitionName : '#/definitions/'.$definitionName;
  116. if ($forceCollection || (OperationType::COLLECTION === $operationType && 'POST' !== $method)) {
  117. $schema['type'] = 'array';
  118. $schema['items'] = ['$ref' => $ref];
  119. } else {
  120. $schema['$ref'] = $ref;
  121. }
  122. }
  124. $definitions = $schema->getDefinitions();
  125. if (isset($definitions[$definitionName])) {
  126. // Already computed
  127. return $schema;
  128. }
  130. /** @var \ArrayObject<string, mixed> $definition */
  131. $definition = new \ArrayObject(['type' => 'object']);
  132. $definitions[$definitionName] = $definition;
  134. if ($resourceMetadata instanceof ResourceMetadata) {
  135. $definition['description'] = $resourceMetadata->getDescription() ?? '';
  136. } else {
  137. $definition['description'] = $operation ? ($operation->getDescription() ?? '') : '';
  138. }
  140. // additionalProperties are allowed by default, so it does not need to be set explicitly, unless allow_extra_attributes is false
  141. // See https://json-schema.org/understanding-json-schema/reference/object.html#properties
  142. if (false === ($serializerContext[AbstractNormalizer::ALLOW_EXTRA_ATTRIBUTES] ?? true)) {
  143. $definition['additionalProperties'] = false;
  144. }
  146. // see https://github.com/json-schema-org/json-schema-spec/pull/737
  147. if (
  148. Schema::VERSION_SWAGGER !== $version
  149. ) {
  150. if (($resourceMetadata instanceof ResourceMetadata
  151. && ($operationType && $operationName ? $resourceMetadata->getTypedOperationAttribute($operationType, $operationName, 'deprecation_reason', null, true) : $resourceMetadata->getAttribute('deprecation_reason', null))
  152. ) || ($operation && $operation->getDeprecationReason())
  153. ) {
  154. $definition['deprecated'] = true;
  155. }
  156. }
  158. // externalDocs is an OpenAPI specific extension, but JSON Schema allows additional keys, so we always add it
  159. // See https://json-schema.org/latest/json-schema-core.html#rfc.section.6.4
  160. if ($resourceMetadata instanceof ResourceMetadata && $resourceMetadata->getIri()) {
  161. $definition['externalDocs'] = ['url' => $resourceMetadata->getIri()];
  162. } elseif ($operation instanceof HttpOperation && ($operation->getTypes()[0] ?? null)) {
  163. $definition['externalDocs'] = ['url' => $operation->getTypes()[0]];
  164. }
  166. // TODO: getFactoryOptions should be refactored because Item & Collection Operations don't exist anymore (API Platform 3.0)
  167. $options = $this->getFactoryOptions($serializerContext, $validationGroups, $operationType, $operationName, $operation instanceof HttpOperation ? $operation : null);
  168. foreach ($this->propertyNameCollectionFactory->create($inputOrOutputClass, $options) as $propertyName) {
  169. $propertyMetadata = $this->propertyMetadataFactory->create($inputOrOutputClass, $propertyName, $options);
  170. if (!$propertyMetadata->isReadable() && !$propertyMetadata->isWritable()) {
  171. continue;
  172. }
  174. $normalizedPropertyName = $this->nameConverter ? $this->nameConverter->normalize($propertyName, $inputOrOutputClass, $format, $serializerContext) : $propertyName;
  175. if ($propertyMetadata->isRequired()) {
  176. $definition['required'][] = $normalizedPropertyName;
  177. }
  179. $this->buildPropertySchema($schema, $definitionName, $normalizedPropertyName, $propertyMetadata, $serializerContext, $format);
  180. }
  182. return $schema;
  183. }
  185. private function buildPropertySchema(Schema $schema, string $definitionName, string $normalizedPropertyName, $propertyMetadata, array $serializerContext, string $format): void
  186. {
  187. $version = $schema->getVersion();
  188. $swagger = Schema::VERSION_SWAGGER === $version;
  189. $propertySchema = $propertyMetadata->getSchema() ?? [];
  191. if ($propertyMetadata instanceof ApiProperty) {
  192. $additionalPropertySchema = $propertyMetadata->getOpenapiContext() ?? [];
  193. } else {
  194. switch ($version) {
  195. case Schema::VERSION_SWAGGER:
  196. $basePropertySchemaAttribute = 'swagger_context';
  197. break;
  198. case Schema::VERSION_OPENAPI:
  199. $basePropertySchemaAttribute = 'openapi_context';
  200. break;
  201. default:
  202. $basePropertySchemaAttribute = 'json_schema_context';
  203. }
  205. $additionalPropertySchema = $propertyMetadata->getAttributes()[$basePropertySchemaAttribute] ?? [];
  206. }
  208. $propertySchema = array_merge(
  209. $propertySchema,
  210. $additionalPropertySchema
  211. );
  213. if (false === $propertyMetadata->isWritable() && !$propertyMetadata->isInitializable()) {
  214. $propertySchema['readOnly'] = true;
  215. }
  216. if (!$swagger && false === $propertyMetadata->isReadable()) {
  217. $propertySchema['writeOnly'] = true;
  218. }
  219. if (null !== $description = $propertyMetadata->getDescription()) {
  220. $propertySchema['description'] = $description;
  221. }
  223. $deprecationReason = $propertyMetadata instanceof PropertyMetadata ? $propertyMetadata->getAttribute('deprecation_reason') : $propertyMetadata->getDeprecationReason();
  225. // see https://github.com/json-schema-org/json-schema-spec/pull/737
  226. if (!$swagger && null !== $deprecationReason) {
  227. $propertySchema['deprecated'] = true;
  228. }
  229. // externalDocs is an OpenAPI specific extension, but JSON Schema allows additional keys, so we always add it
  230. // See https://json-schema.org/latest/json-schema-core.html#rfc.section.6.4
  231. $iri = $propertyMetadata instanceof PropertyMetadata ? $propertyMetadata->getIri() : $propertyMetadata->getTypes()[0] ?? null;
  232. if (null !== $iri) {
  233. $propertySchema['externalDocs'] = ['url' => $iri];
  234. }
  236. if (!isset($propertySchema['default']) && !empty($default = $propertyMetadata->getDefault())) {
  237. $propertySchema['default'] = $default;
  238. }
  240. if (!isset($propertySchema['example']) && !empty($example = $propertyMetadata->getExample())) {
  241. $propertySchema['example'] = $example;
  242. }
  244. if (!isset($propertySchema['example']) && isset($propertySchema['default'])) {
  245. $propertySchema['example'] = $propertySchema['default'];
  246. }
  248. $valueSchema = [];
  249. // TODO: 3.0 support multiple types, default value of types will be [] instead of null
  250. $type = $propertyMetadata instanceof PropertyMetadata ? $propertyMetadata->getType() : $propertyMetadata->getBuiltinTypes()[0] ?? null;
  251. if (null !== $type) {
  252. if ($isCollection = $type->isCollection()) {
  253. $keyType = method_exists(Type::class, 'getCollectionKeyTypes') ? ($type->getCollectionKeyTypes()[0] ?? null) : $type->getCollectionKeyType();
  254. $valueType = method_exists(Type::class, 'getCollectionValueTypes') ? ($type->getCollectionValueTypes()[0] ?? null) : $type->getCollectionValueType();
  255. } else {
  256. $keyType = null;
  257. $valueType = $type;
  258. }
  260. if (null === $valueType) {
  261. $builtinType = 'string';
  262. $className = null;
  263. } else {
  264. $builtinType = $valueType->getBuiltinType();
  265. $className = $valueType->getClassName();
  266. }
  268. $valueSchema = $this->typeFactory->getType(new Type($builtinType, $type->isNullable(), $className, $isCollection, $keyType, $valueType), $format, $propertyMetadata->isReadableLink(), $serializerContext, $schema);
  269. }
  271. if (\array_key_exists('type', $propertySchema) && \array_key_exists('$ref', $valueSchema)) {
  272. $propertySchema = new \ArrayObject($propertySchema);
  273. } else {
  274. $propertySchema = new \ArrayObject($propertySchema + $valueSchema);
  275. }
  276. $schema->getDefinitions()[$definitionName]['properties'][$normalizedPropertyName] = $propertySchema;
  277. }
  279. private function buildDefinitionName(string $className, string $format = 'json', string $inputOrOutputClass = null, $resourceMetadata = null, array $serializerContext = null): string
  280. {
  281. if ($resourceMetadata) {
  282. $prefix = $resourceMetadata instanceof ResourceMetadata ? $resourceMetadata->getShortName() : $resourceMetadata->getShortName();
  283. }
  285. if (!isset($prefix)) {
  286. $prefix = (new \ReflectionClass($className))->getShortName();
  287. }
  289. if (null !== $inputOrOutputClass && $className !== $inputOrOutputClass) {
  290. $parts = explode('\\', $inputOrOutputClass);
  291. $shortName = end($parts);
  292. $prefix .= '.'.$shortName;
  293. }
  295. if (isset($this->distinctFormats[$format])) {
  296. // JSON is the default, and so isn't included in the definition name
  297. $prefix .= '.'.$format;
  298. }
  300. $definitionName = $serializerContext[OpenApiFactory::OPENAPI_DEFINITION_NAME] ?? $serializerContext[DocumentationNormalizer::SWAGGER_DEFINITION_NAME] ?? null;
  301. if ($definitionName) {
  302. $name = sprintf('%s-%s', $prefix, $definitionName);
  303. } else {
  304. $groups = (array) ($serializerContext[AbstractNormalizer::GROUPS] ?? []);
  305. $name = $groups ? sprintf('%s-%s', $prefix, implode('_', $groups)) : $prefix;
  306. }
  308. return $this->encodeDefinitionName($name);
  309. }
  311. private function encodeDefinitionName(string $name): string
  312. {
  313. return preg_replace('/[^a-zA-Z0-9.\-_]/', '.', $name);
  314. }
  316. private function getMetadata(string $className, string $type = Schema::TYPE_OUTPUT, string $operationType = null, string $operationName = null, array $serializerContext = null): ?array
  317. {
  318. if (!$this->isResourceClass($className)) {
  319. return [
  320. null,
  321. $serializerContext ?? [],
  322. [],
  323. $className,
  324. ];
  325. }
  327. /** @var ResourceMetadata|ResourceMetadataCollection $resourceMetadata */
  328. $resourceMetadata = $this->resourceMetadataFactory->create($className);
  329. $attribute = Schema::TYPE_OUTPUT === $type ? 'output' : 'input';
  330. $operation = ($this->resourceMetadataFactory instanceof ResourceMetadataFactoryInterface) ? null : $resourceMetadata->getOperation($operationName);
  332. if ($this->resourceMetadataFactory instanceof ResourceMetadataFactoryInterface) {
  333. if (null === $operationType || null === $operationName) {
  334. $inputOrOutput = $resourceMetadata->getAttribute($attribute, ['class' => $className]);
  335. } else {
  336. $inputOrOutput = $resourceMetadata->getTypedOperationAttribute($operationType, $operationName, $attribute, ['class' => $className], true);
  337. }
  338. } elseif ($operation) {
  339. $inputOrOutput = (Schema::TYPE_OUTPUT === $type ? $operation->getOutput() : $operation->getInput()) ?? ['class' => $className];
  340. } else {
  341. $inputOrOutput = ['class' => $className];
  342. }
  344. if (null === ($inputOrOutput['class'] ?? $inputOrOutput->class ?? null)) {
  345. // input or output disabled
  346. return null;
  347. }
  349. return [
  350. $resourceMetadata,
  351. $serializerContext ?? $this->getSerializerContext($resourceMetadata, $type, $operationType, $operationName),
  352. $this->getValidationGroups($this->resourceMetadataFactory instanceof ResourceMetadataFactoryInterface ? $resourceMetadata : $operation, $operationType, $operationName),
  353. $inputOrOutput['class'] ?? $inputOrOutput->class,
  354. ];
  355. }
  357. private function getSerializerContext($resourceMetadata, string $type = Schema::TYPE_OUTPUT, string $operationType = null, string $operationName = null): array
  358. {
  359. if ($resourceMetadata instanceof ResourceMetadata) {
  360. $attribute = Schema::TYPE_OUTPUT === $type ? 'normalization_context' : 'denormalization_context';
  361. } else {
  362. $operation = $resourceMetadata->getOperation($operationName);
  363. }
  365. if (null === $operationType || null === $operationName) {
  366. if ($resourceMetadata instanceof ResourceMetadata) {
  367. return $resourceMetadata->getAttribute($attribute, []);
  368. }
  370. return Schema::TYPE_OUTPUT === $type ? ($operation->getNormalizationContext() ?? []) : ($operation->getDenormalizationContext() ?? []);
  371. }
  373. if ($resourceMetadata instanceof ResourceMetadata) {
  374. return $resourceMetadata->getTypedOperationAttribute($operationType, $operationName, $attribute, [], true);
  375. }
  377. return Schema::TYPE_OUTPUT === $type ? ($operation->getNormalizationContext() ?? []) : ($operation->getDenormalizationContext() ?? []);
  378. }
  380. /**
  381. * @param HttpOperation|ResourceMetadata|null $resourceMetadata
  382. */
  383. private function getValidationGroups($resourceMetadata, ?string $operationType, ?string $operationName): array
  384. {
  385. if ($resourceMetadata instanceof ResourceMetadata) {
  386. $attribute = 'validation_groups';
  388. if (null === $operationType || null === $operationName) {
  389. return \is_array($validationGroups = $resourceMetadata->getAttribute($attribute, [])) ? $validationGroups : [];
  390. }
  392. return \is_array($validationGroups = $resourceMetadata->getTypedOperationAttribute($operationType, $operationName, $attribute, [], true)) ? $validationGroups : [];
  393. }
  395. $groups = $resourceMetadata ? ($resourceMetadata->getValidationContext()['groups'] ?? []) : [];
  397. return \is_array($groups) ? $groups : [$groups];
  398. }
  400. /**
  401. * Gets the options for the property name collection / property metadata factories.
  402. */
  403. private function getFactoryOptions(array $serializerContext, array $validationGroups, ?string $operationType, ?string $operationName, HttpOperation $operation = null): array
  404. {
  405. $options = [
  406. /* @see https://github.com/symfony/symfony/blob/v5.1.0/src/Symfony/Component/PropertyInfo/Extractor/ReflectionExtractor.php */
  407. 'enable_getter_setter_extraction' => true,
  408. ];
  410. if (isset($serializerContext[AbstractNormalizer::GROUPS])) {
  411. /* @see https://github.com/symfony/symfony/blob/v4.2.6/src/Symfony/Component/PropertyInfo/Extractor/SerializerExtractor.php */
  412. $options['serializer_groups'] = (array) $serializerContext[AbstractNormalizer::GROUPS];
  413. }
  415. if ($this->resourceMetadataFactory instanceof ResourceMetadataCollectionFactoryInterface && $operation) {
  416. $options['normalization_groups'] = $operation->getNormalizationContext()['groups'] ?? null;
  417. $options['denormalization_groups'] = $operation->getDenormalizationContext()['groups'] ?? null;
  418. }
  420. if (null !== $operationType && null !== $operationName) {
  421. switch ($operationType) {
  422. case OperationType::COLLECTION:
  423. $options['collection_operation_name'] = $operationName;
  424. break;
  425. case OperationType::ITEM:
  426. $options['item_operation_name'] = $operationName;
  427. break;
  428. default:
  429. break;
  430. }
  431. }
  433. if ($validationGroups) {
  434. $options['validation_groups'] = $validationGroups;
  435. }
  437. return $options;
  438. }
  439. }