Add swagger_ui_extra_configuration to Swagger configuration

CHANGELOG.md

@@ -5,7 +5,8 @@
 * Doctrine: Better exception to find which resource is linked to an exception (#3965)
 * Doctrine: Allow mixed type value for date filter (notice if invalid) (#3870)
 * MongoDB: `date_immutable` support (#3940)
-* Add `TraversablePaginator` (#3783)
+* DataProvider: Add `TraversablePaginator` (#3783)
+* Swagger UI: Add `swagger_ui_extra_configuration` to Swagger / OpenAPI configuration (#3731)
 
 ## 2.6.3
 

src/Bridge/Symfony/Bundle/Action/SwaggerUiAction.php

@@ -62,12 +62,13 @@ final class SwaggerUiAction
     private $swaggerVersions;
     private $swaggerUiAction;
     private $assetPackage;
+    private $swaggerUiExtraConfiguration;
 
     /**
      * @param int[]      $swaggerVersions
      * @param mixed|null $assetPackage
      */
-    public function __construct(ResourceNameCollectionFactoryInterface $resourceNameCollectionFactory, ResourceMetadataFactoryInterface $resourceMetadataFactory, NormalizerInterface $normalizer, TwigEnvironment $twig, UrlGeneratorInterface $urlGenerator, string $title = '', string $description = '', string $version = '', $formats = [], $oauthEnabled = false, $oauthClientId = '', $oauthClientSecret = '', $oauthType = '', $oauthFlow = '', $oauthTokenUrl = '', $oauthAuthorizationUrl = '', $oauthScopes = [], bool $showWebby = true, bool $swaggerUiEnabled = false, bool $reDocEnabled = false, bool $graphqlEnabled = false, bool $graphiQlEnabled = false, bool $graphQlPlaygroundEnabled = false, array $swaggerVersions = [2, 3], OpenApiSwaggerUiAction $swaggerUiAction = null, $assetPackage = null)
+    public function __construct(ResourceNameCollectionFactoryInterface $resourceNameCollectionFactory, ResourceMetadataFactoryInterface $resourceMetadataFactory, NormalizerInterface $normalizer, TwigEnvironment $twig, UrlGeneratorInterface $urlGenerator, string $title = '', string $description = '', string $version = '', $formats = [], $oauthEnabled = false, $oauthClientId = '', $oauthClientSecret = '', $oauthType = '', $oauthFlow = '', $oauthTokenUrl = '', $oauthAuthorizationUrl = '', $oauthScopes = [], bool $showWebby = true, bool $swaggerUiEnabled = false, bool $reDocEnabled = false, bool $graphqlEnabled = false, bool $graphiQlEnabled = false, bool $graphQlPlaygroundEnabled = false, array $swaggerVersions = [2, 3], OpenApiSwaggerUiAction $swaggerUiAction = null, $assetPackage = null, array $swaggerUiExtraConfiguration = [])
     {
         $this->resourceNameCollectionFactory = $resourceNameCollectionFactory;
         $this->resourceMetadataFactory = $resourceMetadataFactory;
@@ -93,6 +94,7 @@ public function __construct(ResourceNameCollectionFactoryInterface $resourceName
         $this->graphQlPlaygroundEnabled = $graphQlPlaygroundEnabled;
         $this->swaggerVersions = $swaggerVersions;
         $this->swaggerUiAction = $swaggerUiAction;
+        $this->swaggerUiExtraConfiguration = $swaggerUiExtraConfiguration;
         $this->assetPackage = $assetPackage;
 
         if (null === $this->swaggerUiAction) {
@@ -157,6 +159,7 @@ private function getContext(Request $request, Documentation $documentation): arr
         $swaggerData = [
             'url' => $this->urlGenerator->generate('api_doc', ['format' => 'json']),
             'spec' => $this->normalizer->normalize($documentation, 'json', $swaggerContext),
+            'extraConfiguration' => $this->swaggerUiExtraConfiguration,
         ];
 
         $swaggerData['oauth'] = [

src/Bridge/Symfony/Bundle/DependencyInjection/ApiPlatformExtension.php

@@ -397,6 +397,7 @@ private function registerSwaggerConfiguration(ContainerBuilder $container, array
         $container->setParameter('api_platform.enable_swagger_ui', $config['enable_swagger_ui']);
         $container->setParameter('api_platform.enable_re_doc', $config['enable_re_doc']);
         $container->setParameter('api_platform.swagger.api_keys', $config['swagger']['api_keys']);
+        $container->setParameter('api_platform.swagger_ui.extra_configuration', $config['openapi']['swagger_ui_extra_configuration'] ?? $config['swagger']['swagger_ui_extra_configuration']);
 
         if (true === $config['openapi']['backward_compatibility_layer']) {
             $container->getDefinition('api_platform.swagger.normalizer.documentation')->addArgument($container->getDefinition('api_platform.openapi.normalizer'));

src/Bridge/Symfony/Bundle/DependencyInjection/Configuration.php

@@ -339,6 +339,14 @@ private function addSwaggerSection(ArrayNodeDefinition $rootNode): void
                                 ->end()
                             ->end()
                         ->end()
+                        ->variableNode('swagger_ui_extra_configuration')
+                            ->defaultValue([])
+                            ->validate()
+                                ->ifTrue(static function ($v) { return false === \is_array($v); })
+                                ->thenInvalid('The swagger_ui_extra_configuration parameter must be an array.')
+                            ->end()
+                            ->info('To pass extra configuration to Swagger UI, like docExpansion or filter.')
+                        ->end()
                     ->end()
                 ->end()
             ->end();
@@ -492,6 +500,14 @@ private function addOpenApiSection(ArrayNodeDefinition $rootNode): void
                                 ->scalarNode('url')->defaultNull()->info('URL to the license used for the API. MUST be in the format of a URL.')->end()
                             ->end()
                         ->end()
+                        ->variableNode('swagger_ui_extra_configuration')
+                            ->defaultValue([])
+                            ->validate()
+                                ->ifTrue(static function ($v) { return false === \is_array($v); })
+                                ->thenInvalid('The swagger_ui_extra_configuration parameter must be an array.')
+                            ->end()
+                            ->info('To pass extra configuration to Swagger UI, like docExpansion or filter.')
+                        ->end()
                     ->end()
                 ->end()
             ->end();

src/Bridge/Symfony/Bundle/Resources/config/swagger-ui.xml

@@ -38,6 +38,7 @@
             <argument>%api_platform.swagger.versions%</argument>
             <argument type="service" id="api_platform.swagger_ui.action" />
             <argument>%api_platform.asset_package%</argument>
+            <argument>%api_platform.swagger_ui.extra_configuration%</argument>
         </service>
 
         <service id="api_platform.swagger_ui.context" class="ApiPlatform\Core\Bridge\Symfony\Bundle\SwaggerUi\SwaggerUiContext">
@@ -48,6 +49,7 @@
             <argument>%api_platform.graphql.graphiql.enabled%</argument>
             <argument>%api_platform.graphql.graphql_playground.enabled%</argument>
             <argument>%api_platform.asset_package%</argument>
+            <argument>%api_platform.swagger_ui.extra_configuration%</argument>
         </service>
 
         <service id="api_platform.swagger_ui.action" class="ApiPlatform\Core\Bridge\Symfony\Bundle\SwaggerUi\SwaggerUiAction" public="true">

src/Bridge/Symfony/Bundle/Resources/public/init-swagger-ui.js

@@ -41,7 +41,7 @@ window.onload = function() {
     }).observe(document, {childList: true, subtree: true});
 
     const data = JSON.parse(document.getElementById('swagger-data').innerText);
-    const ui = SwaggerUIBundle({
+    const ui = SwaggerUIBundle(Object.assign({
         spec: data.spec,
         dom_id: '#swagger-ui',
         validatorUrl: null,
@@ -54,7 +54,7 @@ window.onload = function() {
             SwaggerUIBundle.plugins.DownloadUrl,
         ],
         layout: 'StandaloneLayout',
-    });
+    }, data.extraConfiguration));
 
     if (data.oauth.enabled) {
         ui.initOAuth({

src/Bridge/Symfony/Bundle/SwaggerUi/SwaggerUiAction.php

@@ -86,6 +86,7 @@ public function __invoke(Request $request)
                 'clientId' => $this->oauthClientId,
                 'clientSecret' => $this->oauthClientSecret,
             ],
+            'extraConfiguration' => $this->swaggerUiContext->getExtraConfiguration(),
         ];
 
         if ($request->isMethodSafe() && null !== $resourceClass = $request->attributes->get('_api_resource_class')) {

src/Bridge/Symfony/Bundle/SwaggerUi/SwaggerUiContext.php

@@ -22,8 +22,9 @@ final class SwaggerUiContext
     private $graphiQlEnabled;
     private $graphQlPlaygroundEnabled;
     private $assetPackage;
+    private $extraConfiguration;
 
-    public function __construct(bool $swaggerUiEnabled = false, bool $showWebby = true, bool $reDocEnabled = false, bool $graphQlEnabled = false, bool $graphiQlEnabled = false, bool $graphQlPlaygroundEnabled = false, $assetPackage = null)
+    public function __construct(bool $swaggerUiEnabled = false, bool $showWebby = true, bool $reDocEnabled = false, bool $graphQlEnabled = false, bool $graphiQlEnabled = false, bool $graphQlPlaygroundEnabled = false, $assetPackage = null, array $extraConfiguration = [])
     {
         $this->swaggerUiEnabled = $swaggerUiEnabled;
         $this->showWebby = $showWebby;
@@ -32,6 +33,7 @@ public function __construct(bool $swaggerUiEnabled = false, bool $showWebby = tr
         $this->graphiQlEnabled = $graphiQlEnabled;
         $this->graphQlPlaygroundEnabled = $graphQlPlaygroundEnabled;
         $this->assetPackage = $assetPackage;
+        $this->extraConfiguration = $extraConfiguration;
     }
 
     public function isSwaggerUiEnabled(): bool
@@ -68,4 +70,9 @@ public function getAssetPackage(): ?string
     {
         return $this->assetPackage;
     }
+
+    public function getExtraConfiguration(): array
+    {
+        return $this->extraConfiguration;
+    }
 }

tests/Bridge/Symfony/Bundle/Action/SwaggerUiActionTest.php

@@ -89,6 +89,7 @@ public function getInvokeParameters()
             'swagger_data' => [
                 'url' => '/url',
                 'spec' => self::SPEC,
+                'extraConfiguration' => [],
                 'oauth' => [
                     'enabled' => false,
                     'clientId' => '',
@@ -123,6 +124,7 @@ public function getInvokeParameters()
             'swagger_data' => [
                 'url' => '/url',
                 'spec' => self::SPEC,
+                'extraConfiguration' => [],
                 'oauth' => [
                     'enabled' => false,
                     'clientId' => '',
@@ -180,6 +182,7 @@ public function testDoNotRunCurrentRequest(Request $request)
             'swagger_data' => [
                 'url' => '/url',
                 'spec' => self::SPEC,
+                'extraConfiguration' => [],
                 'oauth' => [
                     'enabled' => false,
                     'clientId' => '',

tests/Bridge/Symfony/Bundle/DependencyInjection/ApiPlatformExtensionTest.php

@@ -244,6 +244,7 @@ public function testSetNameConverter()
         $containerBuilderProphecy->hasParameter('kernel.debug')->willReturn(true);
         $containerBuilderProphecy->getParameter('kernel.debug')->willReturn(false);
         $containerBuilderProphecy->setAlias('api_platform.name_converter', $nameConverterId)->shouldBeCalled();
+        $containerBuilderProphecy->setParameter('api_platform.swagger_ui.extra_configuration', [])->shouldBeCalled();
 
         $containerBuilder = $containerBuilderProphecy->reveal();
 
@@ -1172,6 +1173,7 @@ private function getBaseContainerBuilderProphecy(array $doctrineIntegrationsToLo
         if ($hasSwagger) {
             $parameters['api_platform.swagger.versions'] = [2, 3];
             $parameters['api_platform.swagger.api_keys'] = [];
+            $parameters['api_platform.swagger_ui.extra_configuration'] = [];
         } else {
             $parameters['api_platform.swagger.versions'] = [];
         }

tests/Bridge/Symfony/Bundle/DependencyInjection/ConfigurationTest.php

@@ -150,6 +150,7 @@ private function runDefaultConfigTests(array $doctrineIntegrationsToLoad = ['orm
             'swagger' => [
                 'versions' => [2, 3],
                 'api_keys' => [],
+                'swagger_ui_extra_configuration' => [],
             ],
             'eager_loading' => [
                 'enabled' => true,
@@ -219,6 +220,7 @@ private function runDefaultConfigTests(array $doctrineIntegrationsToLoad = ['orm
                     'url' => null,
                 ],
                 'backward_compatibility_layer' => true,
+                'swagger_ui_extra_configuration' => [],
             ],
         ], $config);
     }

tests/Bridge/Symfony/Bundle/SwaggerUi/SwaggerUiActionTest.php

@@ -99,6 +99,7 @@ public function getInvokeParameters()
                     'authorizationUrl' => '',
                     'scopes' => [],
                 ],
+                'extraConfiguration' => [],
                 'shortName' => 'F',
                 'operationId' => 'getFCollection',
                 'id' => null,
@@ -133,6 +134,7 @@ public function getInvokeParameters()
                     'authorizationUrl' => '',
                     'scopes' => [],
                 ],
+                'extraConfiguration' => [],
                 'shortName' => 'F',
                 'operationId' => 'getFItem',
                 'id' => null,
@@ -185,6 +187,7 @@ public function testDoNotRunCurrentRequest(Request $request)
                     'authorizationUrl' => '',
                     'scopes' => [],
                 ],
+                'extraConfiguration' => [],
             ],
         ])->shouldBeCalled()->willReturn('');