feat(Preview): Added OpenAPI decorator to document _preview query p…

…aram and JWT security

lib/RoadizCoreBundle/config/services.yaml

@@ -119,6 +119,12 @@ services:
         public: true
 
 
+    RZ\Roadiz\CoreBundle\Api\OpenApi\PreviewDecorator:
+        decorates: 'api_platform.openapi.factory'
+        decoration_priority: 100
+        arguments: [ '@RZ\Roadiz\CoreBundle\Api\OpenApi\PreviewDecorator.inner' ]
+        autoconfigure: false
+
     RZ\Roadiz\CoreBundle\Api\OpenApi\JwtDecorator:
         decorates: 'api_platform.openapi.factory'
         arguments: [ '@RZ\Roadiz\CoreBundle\Api\OpenApi\JwtDecorator.inner' ]

lib/RoadizCoreBundle/src/Api/OpenApi/PreviewDecorator.php

@@ -0,0 +1,54 @@
+<?php
+
+declare(strict_types=1);
+
+namespace RZ\Roadiz\CoreBundle\Api\OpenApi;
+
+use ApiPlatform\OpenApi\Factory\OpenApiFactoryInterface;
+use ApiPlatform\OpenApi\Model;
+use ApiPlatform\OpenApi\Model\PathItem;
+use ApiPlatform\OpenApi\OpenApi;
+
+final class PreviewDecorator implements OpenApiFactoryInterface
+{
+    private OpenApiFactoryInterface $decorated;
+
+    public function __construct(
+        OpenApiFactoryInterface $decorated
+    ) {
+        $this->decorated = $decorated;
+    }
+
+    public function __invoke(array $context = []): OpenApi
+    {
+        $openApi = ($this->decorated)($context);
+        /** @var PathItem[] $paths */
+        $paths = $openApi->getPaths()->getPaths();
+        // For each GET path, add a new query parameter `_preview` to force preview mode
+        foreach ($paths as $path => $pathItem) {
+            $operation = $pathItem->getGet();
+            if (null !== $operation) {
+                $responses = $operation->getResponses();
+                $responses['401'] = new Model\Response(
+                    description: 'Invalid JWT Token'
+                );
+
+                $newOperation = $operation->withParameters([
+                    ...$operation->getParameters(),
+                    (new Model\Parameter(
+                        '_preview',
+                        'query',
+                        'Enables preview mode (requires a valid bearer JWT token)',
+                        false
+                    ))->withSchema(['type' => 'boolean'])->withExample('1')
+                ])->withSecurity([
+                    ...$operation->getSecurity() ?? [],
+                    ['JWT' => []]
+                ])->withResponses($responses);
+                $openApi->getPaths()->addPath($path, $pathItem->withGet($newOperation));
+            }
+        }
+
+        return $openApi;
+    }
+}

lib/RoadizCoreBundle/src/Api/OpenApi/WebResponseDecorator.php

@@ -21,17 +21,25 @@ public function __construct(
     public function __invoke(array $context = []): OpenApi
     {
         $openApi = ($this->decorated)($context);
-        $schemas = $openApi->getComponents()->getSchemas();
         $pathItem = $openApi->getPaths()->getPath('/api/web_response_by_path');
         $operation = $pathItem->getGet();
 
         $openApi->getPaths()->addPath('/api/web_response_by_path', $pathItem->withGet(
-            $operation->withParameters([new Model\Parameter(
-                'path',
-                'query',
-                'Resource path, or `/` for home page',
-                true,
-            )])
+            $operation->withParameters([
+                // override completely parameters
+                new Model\Parameter(
+                    'path',
+                    'query',
+                    'Resource path, or `/` for home page',
+                    true,
+                ),
+                (new Model\Parameter(
+                    '_preview',
+                    'query',
+                    'Enables preview mode (requires a valid bearer JWT token)',
+                    false
+                ))->withSchema(['type' => 'boolean'])->withExample('1')
+            ])
         ));
 
         return $openApi;