feat: add support for Scalar UI (#2711)

## Description

Adds support for https://scalar.com as an alternative API documentation
UI renderer, alongside the existing SwaggerUI, Redocly, and Stoplight
Elements options.

What's included:
- New scalar renderer constant in Renderer.php
- scalar_config configuration node to pass
https://scalar.com/products/api-references/configuration
- Dedicated Twig template (templates/Scalar/index.html.twig) with
bundled standalone JS
- New routing file (config/routing/scalar.php) for serving the Scalar UI
- Service definition for the Scalar controller
- Documentation update in docs/configuration_reference.rst

Closes #...

## What type of PR is this? (check all applicable)
- [ ] Bug Fix
- [x] Feature
- [ ] Refactor
- [ ] Deprecation
- [ ] Breaking Change
- [ ] Documentation Update
- [ ] CI

## Checklist
- [x] I have made corresponding changes to the documentation (`docs/`)

---------

Co-authored-by: djordy <djordy.koert@yoursurprise.com>

Author: maks-oleksyuk

.github/workflows/dependabot.yml

@@ -27,6 +27,10 @@ jobs:
         run: yarn run swagger
       - name: Redocly
         run: yarn run redoc
+      - name: Scalar
+        run: yarn run scalar
+      - name: Stoplight
+        run: yarn run stoplight
       - uses: stefanzweifel/git-auto-commit-action@v7
         with:
           commit_message: "[dependabot-skip] Update UI files"

config/routing/scalar.php

@@ -0,0 +1,21 @@
+<?php
+
+declare(strict_types=1);
+
+/*
+ * This file is part of the NelmioApiDocBundle package.
+ *
+ * (c) Nelmio
+ *
+ * For the full copyright and license information, please view the LICENSE
+ * file that was distributed with this source code.
+ */
+
+use Symfony\Component\HttpFoundation\Request;
+use Symfony\Component\Routing\Loader\Configurator\RoutingConfigurator;
+
+return static function (RoutingConfigurator $routes): void {
+    $routes->add('nelmio_api_doc.scalar', '/')
+        ->controller('nelmio_api_doc.controller.scalar')
+        ->methods([Request::METHOD_GET]);
+};

config/services.php

@@ -33,6 +33,13 @@
                'redocly',
            ])
 
+       ->set('nelmio_api_doc.controller.scalar', \Nelmio\ApiDocBundle\Controller\SwaggerUiController::class)
+           ->public()
+           ->args([
+               service('nelmio_api_doc.render_docs'),
+               'scalar',
+           ])
+
        ->set('nelmio_api_doc.controller.stoplight', \Nelmio\ApiDocBundle\Controller\SwaggerUiController::class)
            ->public()
            ->args([

docs/configuration_reference.rst

@@ -42,6 +42,8 @@ The bundle configuration is stored under the ``nelmio_api_doc`` key in your appl
             swagger_ui_config: []
             # https://redocly.com/docs/redoc/config/
             redocly_config: []
+            # https://scalar.com/products/api-references/configuration
+            scalar_config: []
             # https://docs.stoplight.io/docs/elements/b074dc47b2826-elements-configuration-options
             stoplight_config: []
         # Filter the routes that are documented

phpstan-baseline.neon

@@ -27,7 +27,7 @@ parameters:
 		-
 			message: '#^Call to method render\(\) on an unknown class Twig_Environment\.$#'
 			identifier: class.notFound
-			count: 3
+			count: 4
 			path: src/Render/Html/HtmlOpenApiRenderer.php
 
 		-

public/scalar/scalar.standalone.js

@@ -97,6 +97,11 @@ public function getConfigTreeBuilder(): TreeBuilder
                             ->addDefaultsIfNotSet()
                             ->ignoreExtraKeys(false)
                         ->end()
+                        ->arrayNode('scalar_config')
+                            ->info('https://scalar.com/products/api-references/configuration')
+                            ->addDefaultsIfNotSet()
+                            ->ignoreExtraKeys(false)
+                        ->end()
                         ->arrayNode('stoplight_config')
                             ->info('https://docs.stoplight.io/docs/elements/b074dc47b2826-elements-configuration-options')
                             ->addDefaultsIfNotSet()

src/DependencyInjection/Configuration.php

@@ -51,6 +51,17 @@ public function render(OpenApi $spec, array $options = []): string
             );
         }
 
+        if (isset($options['ui_renderer']) && Renderer::SCALAR === $options['ui_renderer']) {
+            return $this->twig->render(
+                '@NelmioApiDoc/Scalar/index.html.twig',
+                [
+                    'swagger_data' => ['spec' => json_decode($spec->toJson(), true)],
+                    'assets_mode' => $options['assets_mode'],
+                    'scalar_config' => $options['scalar_config'],
+                ]
+            );
+        }
+
         if (isset($options['ui_renderer']) && Renderer::STOPLIGHT === $options['ui_renderer']) {
             return $this->twig->render(
                 '@NelmioApiDoc/Stoplight/index.html.twig',

src/Render/Html/HtmlOpenApiRenderer.php

@@ -15,5 +15,6 @@ class Renderer
 {
     public const REDOCLY = 'redocly';
     public const SWAGGERUI = 'swaggerui';
+    public const SCALAR = 'scalar';
     public const STOPLIGHT = 'stoplight';
 }

src/Render/Html/Renderer.php

@@ -0,0 +1,23 @@
+<!DOCTYPE html>
+<html>
+<head>
+    {% block meta %}
+        <meta charset="UTF-8">
+        <meta name="viewport" content="width=device-width, initial-scale=1, shrink-to-fit=no">
+    {% endblock meta %}
+    <title>{% block title %}{{ swagger_data.spec.info.title }}{% endblock title %}</title>
+</head>
+<body>
+    {% block swagger_ui %}
+        <script id="api-reference" type="application/json">{{ swagger_data.spec|json_encode(65)|raw }}</script>
+    {% endblock swagger_ui %}
+    {% block swagger_initialization %}
+        {% if scalar_config is not empty %}
+        <script>
+            document.getElementById('api-reference').dataset.configuration = JSON.stringify({{ scalar_config|json_encode(65)|raw }});
+        </script>
+        {% endif %}
+        {{ nelmioAsset(assets_mode, 'scalar/scalar.standalone.js') }}
+    {% endblock swagger_initialization %}
+</body>
+</html>