New configuration API (experimental)

src/Configuration/DocumentTransformers.php

@@ -0,0 +1,52 @@
+<?php
+
+namespace Dedoc\Scramble\Configuration;
+
+use Illuminate\Support\Arr;
+
+class DocumentTransformers
+{
+    protected array $transformers = [];
+
+    protected array $appends = [];
+
+    protected array $prepends = [];
+
+    public function append(array|callable|string $transformers)
+    {
+        $this->appends = array_merge(
+            $this->appends,
+            Arr::wrap($transformers)
+        );
+
+        return $this;
+    }
+
+    public function prepend(array|callable|string $transformers)
+    {
+        $this->prepends = array_merge(
+            $this->prepends,
+            Arr::wrap($transformers)
+        );
+
+        return $this;
+    }
+
+    public function use(array $transformers)
+    {
+        $this->transformers = $transformers;
+
+        return $this;
+    }
+
+    public function all(): array
+    {
+        $base = $this->transformers;
+
+        return array_values(array_unique([
+            ...$this->prepends,
+            ...$base,
+            ...$this->appends,
+        ], SORT_REGULAR));
+    }
+}

src/Configuration/GeneratorConfigCollection.php

@@ -0,0 +1,57 @@
+<?php
+
+namespace Dedoc\Scramble\Configuration;
+
+use Dedoc\Scramble\GeneratorConfig;
+use Dedoc\Scramble\Scramble;
+use Illuminate\Routing\Router;
+use LogicException;
+
+class GeneratorConfigCollection
+{
+    /**
+     * @var array<string, GeneratorConfig>
+     */
+    private array $apis = [];
+
+    public function __construct()
+    {
+        $this->apis[Scramble::DEFAULT_API] = $this->buildDefaultApiConfiguration();
+    }
+
+    private function buildDefaultApiConfiguration(): GeneratorConfig
+    {
+        return (new GeneratorConfig)
+            ->expose(
+                ui: fn (Router $router, $action) => $router->get('docs/api', $action)->name('scramble.docs.ui'),
+                document: fn (Router $router, $action) => $router->get('docs/api.json', $action)->name('scramble.docs.document'),
+            );
+    }
+
+    public function get(string $name): GeneratorConfig
+    {
+        if (! array_key_exists($name, $this->apis)) {
+            throw new LogicException("$name API is not registered. Register the API using `Scramble::registerApi` first.");
+        }
+
+        return $this->apis[$name];
+    }
+
+    public function register(string $name, array $config): GeneratorConfig
+    {
+        $this->apis[$name] = $generatorConfig = new GeneratorConfig(
+            config: array_merge(config('scramble') ?: [], $config),
+            parametersExtractors: $this->apis[Scramble::DEFAULT_API]->parametersExtractors,
+            operationTransformers: $this->apis[Scramble::DEFAULT_API]->operationTransformers,
+            documentTransformers: $this->apis[Scramble::DEFAULT_API]->documentTransformers,
+            serverVariables: $this->apis[Scramble::DEFAULT_API]->serverVariables,
+        );
+
+        return $generatorConfig;
+    }
+
+    public function all(): array
+    {
+        return $this->apis;
+    }
+}

src/Configuration/OperationTransformers.php

@@ -0,0 +1,63 @@
+<?php
+
+namespace Dedoc\Scramble\Configuration;
+
+use Dedoc\Scramble\Support\OperationExtensions\DeprecationExtension;
+use Dedoc\Scramble\Support\OperationExtensions\ErrorResponsesExtension;
+use Dedoc\Scramble\Support\OperationExtensions\RequestBodyExtension;
+use Dedoc\Scramble\Support\OperationExtensions\RequestEssentialsExtension;
+use Dedoc\Scramble\Support\OperationExtensions\ResponseExtension;
+use Illuminate\Support\Arr;
+
+class OperationTransformers
+{
+    protected array $transformers = [];
+
+    protected array $appends = [];
+
+    protected array $prepends = [];
+
+    public function append(array|callable|string $transformers)
+    {
+        $this->appends = array_merge(
+            $this->appends,
+            Arr::wrap($transformers)
+        );
+
+        return $this;
+    }
+
+    public function prepend(array|callable|string $transformers)
+    {
+        $this->prepends = array_merge(
+            $this->prepends,
+            Arr::wrap($transformers)
+        );
+
+        return $this;
+    }
+
+    public function use(array $transformers)
+    {
+        $this->transformers = $transformers;
+
+        return $this;
+    }
+
+    public function all(): array
+    {
+        $base = $this->transformers ?: [
+            RequestEssentialsExtension::class,
+            RequestBodyExtension::class,
+            ErrorResponsesExtension::class,
+            ResponseExtension::class,
+            DeprecationExtension::class,
+        ];
+
+        return array_values(array_unique([
+            ...$this->prepends,
+            ...$base,
+            ...$this->appends,
+        ], SORT_REGULAR));
+    }
+}

src/Configuration/ServerVariables.php

@@ -0,0 +1,32 @@
+<?php
+
+namespace Dedoc\Scramble\Configuration;
+
+use Dedoc\Scramble\Support\Generator\ServerVariable;
+
+class ServerVariables
+{
+    /**
+     * @param  array<string, ServerVariable>  $items
+     */
+    public function __construct(public array $items = []) {}
+
+    public function use(array $items)
+    {
+        $this->items = $items;
+
+        return $this;
+    }
+
+    public function all()
+    {
+        return $this->items;
+    }
+
+    public function set(string $name, ServerVariable $serverVariable)
+    {
+        $this->items[$name] = $serverVariable;
+
+        return $this;
+    }
+}

src/Contracts/DocumentTransformer.php

@@ -0,0 +1,11 @@
+<?php
+
+namespace Dedoc\Scramble\Contracts;
+
+use Dedoc\Scramble\OpenApiContext;
+use Dedoc\Scramble\Support\Generator\OpenApi;
+
+interface DocumentTransformer
+{
+    public function handle(OpenApi $document, OpenApiContext $context);
+}

src/Contracts/OperationTransformer.php

@@ -0,0 +1,11 @@
+<?php
+
+namespace Dedoc\Scramble\Contracts;
+
+use Dedoc\Scramble\Support\Generator\Operation;
+use Dedoc\Scramble\Support\RouteInfo;
+
+interface OperationTransformer
+{
+    public function handle(Operation $operation, RouteInfo $routeInfo);
+}

src/Extensions/OperationExtension.php

@@ -2,13 +2,14 @@
 
 namespace Dedoc\Scramble\Extensions;
 
+use Dedoc\Scramble\Contracts\OperationTransformer;
 use Dedoc\Scramble\GeneratorConfig;
 use Dedoc\Scramble\Infer;
 use Dedoc\Scramble\Support\Generator\Operation;
 use Dedoc\Scramble\Support\Generator\TypeTransformer;
 use Dedoc\Scramble\Support\RouteInfo;
 
-abstract class OperationExtension
+abstract class OperationExtension implements OperationTransformer
 {
     public function __construct(
         protected Infer $infer,

src/Generator.php

@@ -5,8 +5,8 @@
 use Dedoc\Scramble\Attributes\ExcludeAllRoutesFromDocs;
 use Dedoc\Scramble\Attributes\ExcludeRouteFromDocs;
 use Dedoc\Scramble\Exceptions\RouteAware;
-use Dedoc\Scramble\Infer\Services\FileParser;
 use Dedoc\Scramble\OpenApiVisitor\SchemaEnforceVisitor;
+use Dedoc\Scramble\Support\ContainerUtils;
 use Dedoc\Scramble\Support\Generator\Components;
 use Dedoc\Scramble\Support\Generator\InfoObject;
 use Dedoc\Scramble\Support\Generator\OpenApi;
@@ -33,8 +33,6 @@ class Generator
 
     public function __construct(
         private OperationBuilder $operationBuilder,
-        private ServerFactory $serverFactory,
-        private FileParser $fileParser,
         private Infer $infer
     ) {}
 
@@ -91,10 +89,14 @@ public function __invoke(?GeneratorConfig $config = null)
 
         $this->moveSameAlternativeServersToPath($openApi);
 
-        if ($afterOpenApiGenerated = $config->afterOpenApiGenerated()) {
-            foreach ($afterOpenApiGenerated as $openApiTransformer) {
-                $openApiTransformer($openApi, $context);
-            }
+        foreach ($config->documentTransformers->all() as $openApiTransformer) {
+            $openApiTransformer = is_callable($openApiTransformer)
+                ? $openApiTransformer
+                : ContainerUtils::makeContextable($openApiTransformer, [
+                    TypeTransformer::class => $typeTransformer,
+                ]);
+
+            $openApiTransformer($openApi, $context);
         }
 
         return $openApi->toArray();
@@ -130,7 +132,7 @@ private function makeOpenApi(GeneratorConfig $config)
         ];
         foreach ($servers as $description => $url) {
             $openApi->addServer(
-                $this->serverFactory->make(url($url ?: '/'), $description)
+                (new ServerFactory($config->serverVariables->all()))->make(url($url ?: '/'), $description)
             );
         }