Add oneOf + discriminator support

phpstan-baseline.neon

@@ -1875,66 +1875,6 @@ parameters:
 			count: 2
 			path: src/Support/Generator/ClassBasedReference.php
 
-		-
-			message: '#^Method Dedoc\\Scramble\\Support\\Generator\\Combined\\AllOf\:\:setItems\(\) has no return type specified\.$#'
-			identifier: missingType.return
-			count: 1
-			path: src/Support/Generator/Combined/AllOf.php
-
-		-
-			message: '#^Method Dedoc\\Scramble\\Support\\Generator\\Combined\\AllOf\:\:setItems\(\) has parameter \$items with no type specified\.$#'
-			identifier: missingType.parameter
-			count: 1
-			path: src/Support/Generator/Combined/AllOf.php
-
-		-
-			message: '#^Method Dedoc\\Scramble\\Support\\Generator\\Combined\\AllOf\:\:toArray\(\) has no return type specified\.$#'
-			identifier: missingType.return
-			count: 1
-			path: src/Support/Generator/Combined/AllOf.php
-
-		-
-			message: '#^Unable to resolve the template type TKey in call to function collect$#'
-			identifier: argument.templateType
-			count: 1
-			path: src/Support/Generator/Combined/AllOf.php
-
-		-
-			message: '#^Unable to resolve the template type TValue in call to function collect$#'
-			identifier: argument.templateType
-			count: 1
-			path: src/Support/Generator/Combined/AllOf.php
-
-		-
-			message: '#^Method Dedoc\\Scramble\\Support\\Generator\\Combined\\AnyOf\:\:setItems\(\) has no return type specified\.$#'
-			identifier: missingType.return
-			count: 1
-			path: src/Support/Generator/Combined/AnyOf.php
-
-		-
-			message: '#^Method Dedoc\\Scramble\\Support\\Generator\\Combined\\AnyOf\:\:setItems\(\) has parameter \$items with no type specified\.$#'
-			identifier: missingType.parameter
-			count: 1
-			path: src/Support/Generator/Combined/AnyOf.php
-
-		-
-			message: '#^Method Dedoc\\Scramble\\Support\\Generator\\Combined\\AnyOf\:\:toArray\(\) has no return type specified\.$#'
-			identifier: missingType.return
-			count: 1
-			path: src/Support/Generator/Combined/AnyOf.php
-
-		-
-			message: '#^Unable to resolve the template type TKey in call to function collect$#'
-			identifier: argument.templateType
-			count: 1
-			path: src/Support/Generator/Combined/AnyOf.php
-
-		-
-			message: '#^Unable to resolve the template type TValue in call to function collect$#'
-			identifier: argument.templateType
-			count: 1
-			path: src/Support/Generator/Combined/AnyOf.php
-
 		-
 			message: '''
 				#^Call to deprecated method uniqueSchemaName\(\) of class Dedoc\\Scramble\\Support\\Generator\\Components\:

src/Attributes/Discriminator.php

@@ -0,0 +1,20 @@
+<?php
+
+namespace Dedoc\Scramble\Attributes;
+
+use Attribute;
+
+/**
+ * Documents a class or an interface as a `oneOf` schema of the mapped types.
+ */
+#[Attribute(Attribute::TARGET_CLASS)]
+class Discriminator
+{
+    /**
+     * @param  array<array-key, class-string>  $mapping  Class names of the documented types, optionally keyed by the values of the discriminator property.
+     */
+    public function __construct(
+        public readonly string $propertyName,
+        public readonly array $mapping = [],
+    ) {}
+}

src/Diagnostics/Schema/Se002InvalidDiscriminatorMappingDiagnostic.php

@@ -0,0 +1,39 @@
+<?php
+
+namespace Dedoc\Scramble\Diagnostics\Schema;
+
+use Dedoc\Scramble\Diagnostics\AbstractDiagnostic;
+use Dedoc\Scramble\Diagnostics\ClassContext;
+use Dedoc\Scramble\Diagnostics\CodeLocation;
+use Dedoc\Scramble\Diagnostics\DiagnosticSeverity;
+use ReflectionClass;
+
+class Se002InvalidDiscriminatorMappingDiagnostic extends AbstractDiagnostic
+{
+    /**
+     * @param  class-string  $className
+     */
+    public static function forMappedType(string $className, mixed $mappedType): self
+    {
+        return new self(
+            DiagnosticSeverity::Warning,
+            sprintf(
+                'Cannot document [%s] from the discriminator mapping',
+                is_string($mappedType) ? $mappedType : get_debug_type($mappedType),
+            ),
+            context: new ClassContext($className),
+            codeLocation: CodeLocation::fromReflection(new ReflectionClass($className)),
+            tip: 'The `#[Discriminator]` attribute mapping must consist of the names of existing classes or interfaces.',
+        );
+    }
+
+    public function code(): string
+    {
+        return 'SE002';
+    }
+
+    public function shouldRenderCodeSnippet(): bool
+    {
+        return false;
+    }
+}

src/ScrambleServiceProvider.php

@@ -75,6 +75,7 @@
 use Dedoc\Scramble\Support\TypeToSchemaExtensions\CarbonInterfaceToSchema;
 use Dedoc\Scramble\Support\TypeToSchemaExtensions\CollectionToSchema;
 use Dedoc\Scramble\Support\TypeToSchemaExtensions\CursorPaginatorTypeToSchema;
+use Dedoc\Scramble\Support\TypeToSchemaExtensions\DiscriminatedObjectToSchema;
 use Dedoc\Scramble\Support\TypeToSchemaExtensions\EloquentCollectionToSchema;
 use Dedoc\Scramble\Support\TypeToSchemaExtensions\EnumToSchema;
 use Dedoc\Scramble\Support\TypeToSchemaExtensions\JsonApiAnonymousCollectionTypeToSchema;
@@ -245,6 +246,10 @@ functions: [
                 fn ($e) => is_a($e, TypeToSchemaExtension::class, true),
             ));
 
+            // Resolved after the user extensions, so an explicit `#[Discriminator]` attribute wins over
+            // the extension that would otherwise document the class.
+            $typesToSchemaExtensions[] = DiscriminatedObjectToSchema::class;
+
             $exceptionToResponseExtensions = array_values(array_filter(
                 $extensions,
                 fn ($e) => is_a($e, ExceptionToResponseExtension::class, true),

src/Support/Generator/Combined/AllOf.php

@@ -2,55 +2,10 @@
 
 namespace Dedoc\Scramble\Support\Generator\Combined;
 
-use Dedoc\Scramble\Support\Generator\Types\StringType;
-use Dedoc\Scramble\Support\Generator\Types\Type;
-use InvalidArgumentException;
-
-class AllOf extends Type
+class AllOf extends CombinedType
 {
-    /** @var Type[] */
-    public $items;
-
     public function __construct()
     {
         parent::__construct('allOf');
-        $this->items = [new StringType];
-    }
-
-    public function clone(): static
-    {
-        $clone = parent::clone();
-        $clone->items = array_map(
-            fn (Type $item) => $item->clone(),
-            $clone->items,
-        );
-
-        return $clone;
-    }
-
-    public function toArray()
-    {
-        $parentArray = parent::toArray();
-
-        unset($parentArray['type']);
-
-        return [
-            ...$parentArray,
-            'allOf' => array_map(
-                fn ($item) => $item->toArray(),
-                $this->items,
-            ),
-        ];
-    }
-
-    public function setItems($items)
-    {
-        if (collect($items)->contains(fn ($item) => ! $item instanceof Type)) {
-            throw new InvalidArgumentException('All items should be instances of '.Type::class);
-        }
-
-        $this->items = $items;
-
-        return $this;
     }
 }

src/Support/Generator/Combined/AnyOf.php

@@ -2,55 +2,10 @@
 
 namespace Dedoc\Scramble\Support\Generator\Combined;
 
-use Dedoc\Scramble\Support\Generator\Types\StringType;
-use Dedoc\Scramble\Support\Generator\Types\Type;
-use InvalidArgumentException;
-
-class AnyOf extends Type
+class AnyOf extends CombinedType
 {
-    /** @var Type[] */
-    public $items;
-
     public function __construct()
     {
         parent::__construct('anyOf');
-        $this->items = [new StringType];
-    }
-
-    public function clone(): static
-    {
-        $clone = parent::clone();
-        $clone->items = array_map(
-            fn (Type $item) => $item->clone(),
-            $clone->items,
-        );
-
-        return $clone;
-    }
-
-    public function toArray()
-    {
-        $parentArray = parent::toArray();
-
-        unset($parentArray['type']);
-
-        return [
-            ...$parentArray,
-            'anyOf' => array_map(
-                fn ($item) => $item->toArray(),
-                $this->items,
-            ),
-        ];
-    }
-
-    public function setItems($items)
-    {
-        if (collect($items)->contains(fn ($item) => ! $item instanceof Type)) {
-            throw new InvalidArgumentException('All items should be instances of '.Type::class);
-        }
-
-        $this->items = $items;
-
-        return $this;
     }
 }

src/Support/Generator/Combined/CombinedType.php

@@ -0,0 +1,89 @@
+<?php
+
+namespace Dedoc\Scramble\Support\Generator\Combined;
+
+use Dedoc\Scramble\Support\Generator\Discriminator;
+use Dedoc\Scramble\Support\Generator\Types\StringType;
+use Dedoc\Scramble\Support\Generator\Types\Type;
+use InvalidArgumentException;
+
+/**
+ * Base for the schemas combining other schemas: `allOf`, `anyOf`, and `oneOf`.
+ */
+abstract class CombinedType extends Type
+{
+    /** @var Type[] */
+    public $items;
+
+    public ?Discriminator $discriminator = null;
+
+    public function __construct(string $type)
+    {
+        parent::__construct($type);
+
+        $this->items = [new StringType];
+    }
+
+    public function clone(): static
+    {
+        $clone = parent::clone();
+
+        $clone->items = array_map(
+            fn (Type $item) => $item->clone(),
+            $clone->items,
+        );
+
+        $clone->discriminator = $clone->discriminator?->clone();
+
+        return $clone;
+    }
+
+    /**
+     * @param  array<array-key, mixed>  $items
+     * @return $this
+     */
+    public function setItems($items)
+    {
+        foreach ($items as $item) {
+            if (! $item instanceof Type) {
+                throw new InvalidArgumentException('All items should be instances of '.Type::class);
+            }
+        }
+
+        /** @var Type[] $items */
+        $this->items = $items;
+
+        return $this;
+    }
+
+    public function setDiscriminator(?Discriminator $discriminator): static
+    {
+        $this->discriminator = $discriminator;
+
+        return $this;
+    }
+
+    /**
+     * @return array<string, mixed>
+     */
+    public function toArray()
+    {
+        $parentArray = parent::toArray();
+
+        unset($parentArray['type']);
+
+        $result = [
+            ...$parentArray,
+            $this->type => array_map(
+                fn (Type $item) => $item->toArray(),
+                $this->items,
+            ),
+        ];
+
+        if ($this->discriminator) {
+            $result['discriminator'] = $this->discriminator->toArray();
+        }
+
+        return $result;
+    }
+}

src/Support/Generator/Combined/OneOf.php

@@ -0,0 +1,11 @@
+<?php
+
+namespace Dedoc\Scramble\Support\Generator\Combined;
+
+class OneOf extends CombinedType
+{
+    public function __construct()
+    {
+        parent::__construct('oneOf');
+    }
+}