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

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