Support Rule::enum()->except() (#658)

* Support `Rule::enum()->except()`

* implement enum rule documentation on rule mapper level

---------

Co-authored-by: Christian Flack <christian.flack@gal-digital.de>
Co-authored-by: Roman Lytvynenko <litvinenko95@gmail.com>

src/Support/OperationExtensions/RulesExtractor/RulesMapper.php

@@ -11,6 +11,8 @@
 use Dedoc\Scramble\Support\Generator\Types\UnknownType;
 use Dedoc\Scramble\Support\Generator\TypeTransformer;
 use Dedoc\Scramble\Support\Type\ObjectType;
+use Dedoc\Scramble\Support\Type\TypeHelper;
+use Dedoc\Scramble\Support\Type\Union;
 use Illuminate\Support\Str;
 use Illuminate\Support\Stringable;
 use Illuminate\Validation\Rules\Enum;
@@ -168,9 +170,26 @@ public function enum(Type $_, Enum $rule)
 
         $enumName = $getProtectedValue($rule, 'type');
 
-        return $this->openApiTransformer->transform(
-            new ObjectType($enumName)
-        );
+        $objectType = new ObjectType($enumName);
+
+        $except = $getProtectedValue($rule, 'except');
+        $only = $getProtectedValue($rule, 'only');
+
+        if ($except || $only) {
+            $cases = collect($enumName::cases())
+                ->reject(fn ($case) => in_array($case, $except))
+                ->filter(fn ($case) => !$only || in_array($case, $only));
+
+            if (! isset($cases->first()?->value)) {
+                return new UnknownType("$enumName enum doesnt have values (only/except context)");
+            }
+
+            return $this->openApiTransformer->transform(Union::wrap(
+                $cases->map(fn ($c) => TypeHelper::createTypeFromValue($c->value))->all()
+            ));
+        }
+
+        return $this->openApiTransformer->transform($objectType);
     }
 
     public function image(Type $type)

tests/ValidationRulesDocumentingTest.php

@@ -80,6 +80,38 @@ function validationRulesToDocumentationWithDeep(array $rules)
     assertMatchesSnapshot(collect($params)->map->toArray()->all());
 });
 
+it('extract rules from enum rule with only', function () {
+    $rules = [
+        'status' => (new Enum(StatusValidationEnum::class))->only([StatusValidationEnum::DRAFT, StatusValidationEnum::ARCHIVED]),
+    ];
+
+    $params = app()->make(RulesToParameters::class, ['rules' => $rules])->handle();
+
+    expect($params[0]->toArray()['schema'])->toBe([
+        'type' => 'string',
+        'enum' => [
+            'draft',
+            'archived',
+        ]
+    ]);
+});
+
+it('extract rules from enum rule with except', function () {
+    $rules = [
+        'status' => (new Enum(StatusValidationEnum::class))->except(StatusValidationEnum::DRAFT),
+    ];
+
+    $params = app()->make(RulesToParameters::class, ['rules' => $rules])->handle();
+
+    expect($params[0]->toArray()['schema'])->toBe([
+        'type' => 'string',
+        'enum' => [
+            'published',
+            'archived',
+        ]
+    ]);
+});
+
 it('extract rules from object like rules', function () {
     $rules = [
         'channels.agency' => 'nullable',