Handle activation of swagger through versions (#2998)

GregoireHebert · dunglas · commit d047d85a993b · 2019-08-20T18:08:42.000+02:00
* Add swagger version configuration option

* deprecate enable_swagger option in favour of swagger.versions option

* use first swagger version defined as default

* fix optional parameter

* Set nullable versions for DocumentationAction

* fix phpstan review

* fix php-cs-fixer review

* fix code review

* fix phpstan

* fix code review

* fix SwaggerCommand default value for spec-version option

* fix swagger Command cast int option

* fix phpdoc
diff --git a/src/Bridge/Symfony/Bundle/Action/SwaggerUiAction.php b/src/Bridge/Symfony/Bundle/Action/SwaggerUiAction.php
@@ -56,8 +56,12 @@ final class SwaggerUiAction
     private $graphqlEnabled;
     private $graphiQlEnabled;
     private $graphQlPlaygroundEnabled;
+    private $swaggerVersions;
 
-    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)
+    /**
+     * @param int[] $swaggerVersions
+     */
+    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])
     {
         $this->resourceNameCollectionFactory = $resourceNameCollectionFactory;
         $this->resourceMetadataFactory = $resourceMetadataFactory;
@@ -81,6 +85,7 @@ public function __construct(ResourceNameCollectionFactoryInterface $resourceName
         $this->graphqlEnabled = $graphqlEnabled;
         $this->graphiQlEnabled = $graphiQlEnabled;
         $this->graphQlPlaygroundEnabled = $graphQlPlaygroundEnabled;
+        $this->swaggerVersions = $swaggerVersions;
 
         if (\is_array($formats)) {
             $this->formats = $formats;
@@ -127,7 +132,7 @@ private function getContext(Request $request, Documentation $documentation): arr
             'graphQlPlaygroundEnabled' => $this->graphQlPlaygroundEnabled,
         ];
 
-        $swaggerContext = ['spec_version' => $request->query->getInt('spec_version', 2)];
+        $swaggerContext = ['spec_version' => $request->query->getInt('spec_version', $this->swaggerVersions[0] ?? 2)];
         if ('' !== $baseUrl = $request->getBaseUrl()) {
             $swaggerContext['base_url'] = $baseUrl;
         }
diff --git a/src/Bridge/Symfony/Bundle/Command/SwaggerCommand.php b/src/Bridge/Symfony/Bundle/Command/SwaggerCommand.php
@@ -39,15 +39,20 @@ final class SwaggerCommand extends Command
     private $apiDescription;
     private $apiVersion;
     private $apiFormats;
+    private $swaggerVersions;
 
-    public function __construct(NormalizerInterface $normalizer, ResourceNameCollectionFactoryInterface $resourceNameCollection, string $apiTitle, string $apiDescription, string $apiVersion, array $apiFormats = null)
+    /**
+     * @param int[] $swaggerVersions
+     */
+    public function __construct(NormalizerInterface $normalizer, ResourceNameCollectionFactoryInterface $resourceNameCollection, string $apiTitle, string $apiDescription, string $apiVersion, array $apiFormats = null, array $swaggerVersions = [2, 3])
     {
         $this->normalizer = $normalizer;
         $this->resourceNameCollectionFactory = $resourceNameCollection;
         $this->apiTitle = $apiTitle;
         $this->apiDescription = $apiDescription;
         $this->apiVersion = $apiVersion;
         $this->apiFormats = $apiFormats;
+        $this->swaggerVersions = $swaggerVersions;
 
         if (null !== $apiFormats) {
             @trigger_error(sprintf('Passing a 6th parameter to the constructor of "%s" is deprecated since API Platform 2.5', __CLASS__), E_USER_DEPRECATED);
@@ -66,7 +71,7 @@ protected function configure()
             ->setAliases(['api:swagger:export'])
             ->setDescription('Dump the OpenAPI documentation')
             ->addOption('yaml', 'y', InputOption::VALUE_NONE, 'Dump the documentation in YAML')
-            ->addOption('spec-version', null, InputOption::VALUE_OPTIONAL, 'OpenAPI version to use ("2" or "3")', '2')
+            ->addOption('spec-version', null, InputOption::VALUE_OPTIONAL, sprintf('OpenAPI version to use (%s)', implode(' or ', $this->swaggerVersions)), $this->swaggerVersions[0] ?? 2)
             ->addOption('output', 'o', InputOption::VALUE_OPTIONAL, 'Write output to file')
             ->addOption('api-gateway', null, InputOption::VALUE_NONE, 'API Gateway compatibility');
     }
@@ -77,11 +82,12 @@ protected function configure()
     protected function execute(InputInterface $input, OutputInterface $output)
     {
         $io = new SymfonyStyle($input, $output);
+
         /** @var string $version */
         $version = $input->getOption('spec-version');
 
-        if (!\in_array($version, ['2', '3'], true)) {
-            throw new InvalidOptionException(sprintf('This tool only supports version 2 and 3 of the OpenAPI specification ("%s" given).', $version));
+        if (!\in_array((int) $version, $this->swaggerVersions, true)) {
+            throw new InvalidOptionException(sprintf('This tool only supports versions %s of the OpenAPI specification ("%s" given).', implode(', ', $this->swaggerVersions), $version));
         }
 
         $documentation = new Documentation($this->resourceNameCollectionFactory->create(), $this->apiTitle, $this->apiDescription, $this->apiVersion, $this->apiFormats);
diff --git a/src/Bridge/Symfony/Bundle/DependencyInjection/ApiPlatformExtension.php b/src/Bridge/Symfony/Bundle/DependencyInjection/ApiPlatformExtension.php
@@ -307,7 +307,7 @@ private function registerOAuthConfiguration(ContainerBuilder $container, array $
      */
     private function registerSwaggerConfiguration(ContainerBuilder $container, array $config, XmlFileLoader $loader): void
     {
-        if (!$config['enable_swagger']) {
+        if (empty($config['swagger']['versions'])) {
             return;
         }
 
@@ -320,7 +320,7 @@ private function registerSwaggerConfiguration(ContainerBuilder $container, array
             $container->setParameter('api_platform.enable_re_doc', $config['enable_re_doc']);
         }
 
-        $container->setParameter('api_platform.enable_swagger', $config['enable_swagger']);
+        $container->setParameter('api_platform.swagger.versions', $config['swagger']['versions']);
         $container->setParameter('api_platform.swagger.api_keys', $config['swagger']['api_keys']);
     }
 
diff --git a/src/Bridge/Symfony/Bundle/DependencyInjection/Configuration.php b/src/Bridge/Symfony/Bundle/DependencyInjection/Configuration.php
@@ -56,6 +56,16 @@ public function getConfigTreeBuilder()
         }
 
         $rootNode
+            ->beforeNormalization()
+                ->ifTrue(static function ($v) {
+                    return false === ($v['enable_swagger'] ?? null);
+                })
+                ->then(static function ($v) {
+                    $v['swagger']['versions'] = [];
+
+                    return $v;
+                })
+            ->end()
             ->children()
                 ->scalarNode('title')
                     ->info('The title of the API.')
@@ -236,14 +246,40 @@ private function addGraphQlSection(ArrayNodeDefinition $rootNode): void
 
     private function addSwaggerSection(ArrayNodeDefinition $rootNode): void
     {
+        $defaultVersions = [2, 3];
+
         $rootNode
             ->children()
                 ->arrayNode('swagger')
                     ->addDefaultsIfNotSet()
                     ->children()
-                             ->arrayNode('api_keys')
-                                 ->prototype('array')
-                                    ->children()
+                        ->arrayNode('versions')
+                            ->info('The active versions of OpenAPI to be exported or used in the swagger_ui. The first value is the default.')
+                            ->defaultValue($defaultVersions)
+                            ->beforeNormalization()
+                                ->always(static function ($v) {
+                                    if (!\is_array($v)) {
+                                        $v = [$v];
+                                    }
+
+                                    foreach ($v as &$version) {
+                                        $version = (int) $version;
+                                    }
+
+                                    return $v;
+                                })
+                            ->end()
+                            ->validate()
+                                ->ifTrue(function ($v) use ($defaultVersions) {
+                                    return $v !== array_intersect($v, $defaultVersions);
+                                })
+                                ->thenInvalid(sprintf('Only the versions %s are supported. Got %s.', implode(' and ', $defaultVersions), '%s'))
+                            ->end()
+                            ->prototype('scalar')->end()
+                        ->end()
+                        ->arrayNode('api_keys')
+                            ->prototype('array')
+                                ->children()
                                     ->scalarNode('name')
                                         ->info('The name of the header or query parameter containing the api key.')
                                     ->end()
@@ -252,7 +288,7 @@ private function addSwaggerSection(ArrayNodeDefinition $rootNode): void
                                         ->values(['query', 'header'])
                                     ->end()
                                 ->end()
-                             ->end()
+                            ->end()
                         ->end()
                     ->end()
                 ->end()
diff --git a/src/Bridge/Symfony/Bundle/Resources/config/api.xml b/src/Bridge/Symfony/Bundle/Resources/config/api.xml
@@ -240,6 +240,8 @@
             <argument>%api_platform.title%</argument>
             <argument>%api_platform.description%</argument>
             <argument>%api_platform.version%</argument>
+            <argument>null</argument>
+            <argument on-invalid="null">%api_platform.swagger.versions%</argument>
         </service>
 
         <service id="api_platform.action.exception" class="ApiPlatform\Core\Action\ExceptionAction" public="true">
diff --git a/src/Bridge/Symfony/Bundle/Resources/config/swagger-ui.xml b/src/Bridge/Symfony/Bundle/Resources/config/swagger-ui.xml
@@ -34,6 +34,7 @@
             <argument>%api_platform.graphql.enabled%</argument>
             <argument>%api_platform.graphql.graphiql.enabled%</argument>
             <argument>%api_platform.graphql.graphql_playground.enabled%</argument>
+            <argument>%api_platform.swagger.versions%</argument>
         </service>
 
     </services>
diff --git a/src/Bridge/Symfony/Bundle/Resources/config/swagger.xml b/src/Bridge/Symfony/Bundle/Resources/config/swagger.xml
@@ -31,6 +31,7 @@
             <argument>%api_platform.formats%</argument>
             <argument>%api_platform.collection.pagination.client_enabled%</argument>
             <argument>%api_platform.collection.pagination.enabled_parameter_name%</argument>
+            <argument>%api_platform.swagger.versions%</argument>
             <tag name="serializer.normalizer" priority="-790" />
         </service>
 
@@ -45,6 +46,8 @@
             <argument>%api_platform.title%</argument>
             <argument>%api_platform.description%</argument>
             <argument>%api_platform.version%</argument>
+            <argument>null</argument>
+            <argument>%api_platform.swagger.versions%</argument>
             <tag name="console.command" />
         </service>
 
diff --git a/src/Documentation/Action/DocumentationAction.php b/src/Documentation/Action/DocumentationAction.php
@@ -32,14 +32,19 @@ final class DocumentationAction
     private $version;
     private $formats;
     private $formatsProvider;
-    private $resourceMetadataFactory;
+    private $swaggerVersions;
 
-    public function __construct(ResourceNameCollectionFactoryInterface $resourceNameCollectionFactory, string $title = '', string $description = '', string $version = '', $formatsProvider = null)
+    /**
+     * @param int[]                                $swaggerVersions
+     * @param mixed|array|FormatsProviderInterface $formatsProvider
+     */
+    public function __construct(ResourceNameCollectionFactoryInterface $resourceNameCollectionFactory, string $title = '', string $description = '', string $version = '', $formatsProvider = null, array $swaggerVersions = [2, 3])
     {
         $this->resourceNameCollectionFactory = $resourceNameCollectionFactory;
         $this->title = $title;
         $this->description = $description;
         $this->version = $version;
+        $this->swaggerVersions = $swaggerVersions;
 
         if (null === $formatsProvider) {
             return;
@@ -57,7 +62,7 @@ public function __construct(ResourceNameCollectionFactoryInterface $resourceName
     public function __invoke(Request $request = null): Documentation
     {
         if (null !== $request) {
-            $context = ['base_url' => $request->getBaseUrl(), 'spec_version' => $request->query->getInt('spec_version', 2)];
+            $context = ['base_url' => $request->getBaseUrl(), 'spec_version' => $request->query->getInt('spec_version', $this->swaggerVersions[0] ?? 2)];
             if ($request->query->getBoolean('api_gateway')) {
                 $context['api_gateway'] = true;
             }
diff --git a/src/Swagger/Serializer/DocumentationNormalizer.php b/src/Swagger/Serializer/DocumentationNormalizer.php
@@ -95,7 +95,6 @@ final class DocumentationNormalizer implements NormalizerInterface, CacheableSup
     private $jsonSchemaTypeFactory;
     private $defaultContext = [
         self::BASE_URL => '/',
-        self::SPEC_VERSION => 2,
         ApiGatewayNormalizer::API_GATEWAY => false,
     ];
 
@@ -104,8 +103,9 @@ final class DocumentationNormalizer implements NormalizerInterface, CacheableSup
      * @param ContainerInterface|FilterCollection|null                   $filterLocator
      * @param array|OperationAwareFormatsProviderInterface               $formats
      * @param mixed|null                                                 $jsonSchemaTypeFactory
+     * @param int[]                                                      $swaggerVersions
      */
-    public function __construct(ResourceMetadataFactoryInterface $resourceMetadataFactory, PropertyNameCollectionFactoryInterface $propertyNameCollectionFactory, PropertyMetadataFactoryInterface $propertyMetadataFactory, $jsonSchemaFactory = null, $jsonSchemaTypeFactory = null, OperationPathResolverInterface $operationPathResolver, UrlGeneratorInterface $urlGenerator = null, $filterLocator = null, NameConverterInterface $nameConverter = null, bool $oauthEnabled = false, string $oauthType = '', string $oauthFlow = '', string $oauthTokenUrl = '', string $oauthAuthorizationUrl = '', array $oauthScopes = [], array $apiKeys = [], SubresourceOperationFactoryInterface $subresourceOperationFactory = null, bool $paginationEnabled = true, string $paginationPageParameterName = 'page', bool $clientItemsPerPage = false, string $itemsPerPageParameterName = 'itemsPerPage', $formats = [], bool $paginationClientEnabled = false, string $paginationClientEnabledParameterName = 'pagination', array $defaultContext = [])
+    public function __construct(ResourceMetadataFactoryInterface $resourceMetadataFactory, PropertyNameCollectionFactoryInterface $propertyNameCollectionFactory, PropertyMetadataFactoryInterface $propertyMetadataFactory, $jsonSchemaFactory = null, $jsonSchemaTypeFactory = null, OperationPathResolverInterface $operationPathResolver, UrlGeneratorInterface $urlGenerator = null, $filterLocator = null, NameConverterInterface $nameConverter = null, bool $oauthEnabled = false, string $oauthType = '', string $oauthFlow = '', string $oauthTokenUrl = '', string $oauthAuthorizationUrl = '', array $oauthScopes = [], array $apiKeys = [], SubresourceOperationFactoryInterface $subresourceOperationFactory = null, bool $paginationEnabled = true, string $paginationPageParameterName = 'page', bool $clientItemsPerPage = false, string $itemsPerPageParameterName = 'itemsPerPage', $formats = [], bool $paginationClientEnabled = false, string $paginationClientEnabledParameterName = 'pagination', array $defaultContext = [], array $swaggerVersions = [2, 3])
     {
         if ($jsonSchemaTypeFactory instanceof OperationMethodResolverInterface) {
             @trigger_error(sprintf('Passing an instance of %s to %s() is deprecated since version 2.5 and will be removed in 3.0.', OperationMethodResolverInterface::class, __METHOD__), E_USER_DEPRECATED);
@@ -163,6 +163,8 @@ public function __construct(ResourceMetadataFactoryInterface $resourceMetadataFa
         $this->paginationClientEnabled = $paginationClientEnabled;
         $this->paginationClientEnabledParameterName = $paginationClientEnabledParameterName;
 
+        $this->defaultContext[self::SPEC_VERSION] = $swaggerVersions[0] ?? 2;
+
         $this->defaultContext = array_merge($this->defaultContext, $defaultContext);
     }
 
diff --git a/tests/Bridge/Symfony/Bundle/Command/SwaggerCommandTest.php b/tests/Bridge/Symfony/Bundle/Command/SwaggerCommandTest.php
@@ -43,7 +43,7 @@ protected function setUp(): void
 
     public function testExecuteWithAliasVersion3()
     {
-        $this->tester->run(['command' => 'api:swagger:export', '--spec-version' => '3']);
+        $this->tester->run(['command' => 'api:swagger:export', '--spec-version' => 3]);
 
         $this->assertJson($this->tester->getDisplay());
     }
@@ -57,7 +57,7 @@ public function testExecuteOpenApiVersion2()
 
     public function testExecuteWithYamlVersion3()
     {
-        $this->tester->run(['command' => 'api:swagger:export', '--yaml' => true, '--spec-version' => '3']);
+        $this->tester->run(['command' => 'api:swagger:export', '--yaml' => true, '--spec-version' => 3]);
 
         $result = $this->tester->getDisplay();
         $this->assertYaml($result);
@@ -105,7 +105,7 @@ public function testExecuteOpenApiVersion2WithYaml()
     public function testExecuteWithBadArguments()
     {
         $this->expectException(InvalidOptionException::class);
-        $this->expectExceptionMessage('This tool only supports version 2 and 3 of the OpenAPI specification ("foo" given).');
+        $this->expectExceptionMessage('This tool only supports versions 2, 3 of the OpenAPI specification ("foo" given).');
         $this->tester->run(['command' => 'api:openapi:export', '--spec-version' => 'foo', '--yaml' => true]);
     }
 
diff --git a/tests/Bridge/Symfony/Bundle/DependencyInjection/ApiPlatformExtensionTest.php b/tests/Bridge/Symfony/Bundle/DependencyInjection/ApiPlatformExtensionTest.php
diff --git a/tests/Bridge/Symfony/Bundle/DependencyInjection/ConfigurationTest.php b/tests/Bridge/Symfony/Bundle/DependencyInjection/ConfigurationTest.php
diff --git a/tests/Bridge/Symfony/Routing/ApiLoaderTest.php b/tests/Bridge/Symfony/Routing/ApiLoaderTest.php

Original file line number	Diff line number	Diff line change
`@@ -307,7 +307,7 @@ private function registerOAuthConfiguration(ContainerBuilder $container, array $`
`307`	`307`	`*/`
`308`	`308`	`private function registerSwaggerConfiguration(ContainerBuilder $container, array $config, XmlFileLoader $loader): void`
`309`	`309`	`{`
`310`		`- if (!$config['enable_swagger']) {`
	`310`	`+ if (empty($config['swagger']['versions'])) {`
`311`	`311`	`return;`
`312`	`312`	`}`
`313`	`313`
`@@ -320,7 +320,7 @@ private function registerSwaggerConfiguration(ContainerBuilder $container, array`
`320`	`320`	`$container->setParameter('api_platform.enable_re_doc', $config['enable_re_doc']);`
`321`	`321`	`}`
`322`	`322`
`323`		`- $container->setParameter('api_platform.enable_swagger', $config['enable_swagger']);`
	`323`	`+ $container->setParameter('api_platform.swagger.versions', $config['swagger']['versions']);`
`324`	`324`	`$container->setParameter('api_platform.swagger.api_keys', $config['swagger']['api_keys']);`
`325`	`325`	`}`
`326`	`326`
Original file line number	Diff line number	Diff line change
`@@ -43,7 +43,7 @@ protected function setUp(): void`
`43`	`43`
`44`	`44`	`public function testExecuteWithAliasVersion3()`
`45`	`45`	`{`
`46`		`- $this->tester->run(['command' => 'api:swagger:export', '--spec-version' => '3']);`
	`46`	`+ $this->tester->run(['command' => 'api:swagger:export', '--spec-version' => 3]);`
`47`	`47`
`48`	`48`	`$this->assertJson($this->tester->getDisplay());`
`49`	`49`	`}`
`@@ -57,7 +57,7 @@ public function testExecuteOpenApiVersion2()`
`57`	`57`
`58`	`58`	`public function testExecuteWithYamlVersion3()`
`59`	`59`	`{`
`60`		`- $this->tester->run(['command' => 'api:swagger:export', '--yaml' => true, '--spec-version' => '3']);`
	`60`	`+ $this->tester->run(['command' => 'api:swagger:export', '--yaml' => true, '--spec-version' => 3]);`
`61`	`61`
`62`	`62`	`$result = $this->tester->getDisplay();`
`63`	`63`	`$this->assertYaml($result);`
`@@ -105,7 +105,7 @@ public function testExecuteOpenApiVersion2WithYaml()`
`105`	`105`	`public function testExecuteWithBadArguments()`
`106`	`106`	`{`
`107`	`107`	`$this->expectException(InvalidOptionException::class);`
`108`		`- $this->expectExceptionMessage('This tool only supports version 2 and 3 of the OpenAPI specification ("foo" given).');`
	`108`	`+ $this->expectExceptionMessage('This tool only supports versions 2, 3 of the OpenAPI specification ("foo" given).');`
`109`	`109`	`$this->tester->run(['command' => 'api:openapi:export', '--spec-version' => 'foo', '--yaml' => true]);`
`110`	`110`	`}`
`111`	`111`