Merge pull request #1404 from bifidokk/area-docs

Separated documentation for areas

DependencyInjection/Configuration.php

@@ -48,10 +48,10 @@ final class Configuration implements ConfigurationInterface
                 ->end()
                 ->arrayNode('areas')
                     ->info('Filter the routes that are documented')
-                    ->defaultValue(['default' => ['path_patterns' => [], 'host_patterns' => []]])
+                    ->defaultValue(['default' => ['path_patterns' => [], 'host_patterns' => [], 'documentation' => []]])
                     ->beforeNormalization()
                         ->ifTrue(function ($v) {
-                            return 0 === count($v) || isset($v['path_patterns']) || isset($v['host_patterns']);
+                            return 0 === count($v) || isset($v['path_patterns']) || isset($v['host_patterns']) || isset($v['documentation']);
                         })
                         ->then(function ($v) {
                             return ['default' => $v];
@@ -77,6 +77,13 @@ final class Configuration implements ConfigurationInterface
                                 ->example(['^api\.'])
                                 ->prototype('scalar')->end()
                             ->end()
+                            ->arrayNode('documentation')
+                                ->useAttributeAsKey('key')
+                                ->defaultValue([])
+                                ->info('The documentation used for area')
+                                ->example(['info' => ['title' => 'My App']])
+                                ->prototype('variable')->end()
+                            ->end()
                         ->end()
                     ->end()
                 ->end()

DependencyInjection/NelmioApiDocExtension.php

@@ -13,6 +13,7 @@ namespace Nelmio\ApiDocBundle\DependencyInjection;
 
 use FOS\RestBundle\Controller\Annotations\ParamInterface;
 use Nelmio\ApiDocBundle\ApiDocGenerator;
+use Nelmio\ApiDocBundle\Describer\ExternalDocDescriber;
 use Nelmio\ApiDocBundle\Describer\RouteDescriber;
 use Nelmio\ApiDocBundle\Describer\SwaggerPhpDescriber;
 use Nelmio\ApiDocBundle\ModelDescriber\BazingaHateoasModelDescriber;
@@ -64,27 +65,13 @@ final class NelmioApiDocExtension extends Extension implements PrependExtensionI
             $nameAliases = $this->findNameAliases($config['models']['names'], $area);
 
             $container->register(sprintf('nelmio_api_doc.generator.%s', $area), ApiDocGenerator::class)
-                ->setPublic(false)
+                ->setPublic(true)
                 ->addMethodCall('setAlternativeNames', [$nameAliases])
                 ->setArguments([
                     new TaggedIteratorArgument(sprintf('nelmio_api_doc.describer.%s', $area)),
                     new TaggedIteratorArgument('nelmio_api_doc.model_describer'),
                 ]);
 
-            if (0 === count($areaConfig['path_patterns']) && 0 === count($areaConfig['host_patterns'])) {
-                $container->setDefinition(sprintf('nelmio_api_doc.routes.%s', $area), $routesDefinition)
-                    ->setPublic(false);
-            } else {
-                $container->register(sprintf('nelmio_api_doc.routes.%s', $area), RouteCollection::class)
-                    ->setPublic(false)
-                    ->setFactory([
-                        (new Definition(FilteredRouteCollectionBuilder::class))
-                            ->addArgument($areaConfig),
-                        'filter',
-                    ])
-                    ->addArgument($routesDefinition);
-            }
-
             $container->register(sprintf('nelmio_api_doc.describers.route.%s', $area), RouteDescriber::class)
                 ->setPublic(false)
                 ->setArguments([
@@ -103,6 +90,29 @@ final class NelmioApiDocExtension extends Extension implements PrependExtensionI
                     new Reference('logger'),
                 ])
                 ->addTag(sprintf('nelmio_api_doc.describer.%s', $area), ['priority' => -200]);
+
+            $container->register(sprintf('nelmio_api_doc.describers.config.%s', $area), ExternalDocDescriber::class)
+                ->setPublic(false)
+                ->setArguments([
+                    $areaConfig['documentation'],
+                    true,
+                ])
+                ->addTag(sprintf('nelmio_api_doc.describer.%s', $area), ['priority' => 990]);
+
+            unset($areaConfig['documentation']);
+            if (0 === count($areaConfig['path_patterns']) && 0 === count($areaConfig['host_patterns'])) {
+                $container->setDefinition(sprintf('nelmio_api_doc.routes.%s', $area), $routesDefinition)
+                    ->setPublic(false);
+            } else {
+                $container->register(sprintf('nelmio_api_doc.routes.%s', $area), RouteCollection::class)
+                    ->setPublic(false)
+                    ->setFactory([
+                        (new Definition(FilteredRouteCollectionBuilder::class))
+                            ->addArgument($areaConfig),
+                        'filter',
+                    ])
+                    ->addArgument($routesDefinition);
+            }
         }
 
         $container->register('nelmio_api_doc.generator_locator')

Tests/DependencyInjection/ConfigurationTest.php

@@ -22,16 +22,16 @@ class ConfigurationTest extends TestCase
         $processor = new Processor();
         $config = $processor->processConfiguration(new Configuration(), [['areas' => ['path_patterns' => ['/foo']]]]);
 
-        $this->assertSame(['default' => ['path_patterns' => ['/foo'], 'host_patterns' => []]], $config['areas']);
+        $this->assertSame(['default' => ['path_patterns' => ['/foo'], 'host_patterns' => [], 'documentation' => []]], $config['areas']);
     }
 
     public function testAreas()
     {
         $processor = new Processor();
         $config = $processor->processConfiguration(new Configuration(), [['areas' => $areas = [
-            'default' => ['path_patterns' => ['/foo'], 'host_patterns' => []],
+            'default' => ['path_patterns' => ['/foo'], 'host_patterns' => [], 'documentation' => []],
-            'internal' => ['path_patterns' => ['/internal'], 'host_patterns' => ['^swagger\.']],
+            'internal' => ['path_patterns' => ['/internal'], 'host_patterns' => ['^swagger\.'], 'documentation' => []],
-            'commercial' => ['path_patterns' => ['/internal'], 'host_patterns' => []],
+            'commercial' => ['path_patterns' => ['/internal'], 'host_patterns' => [], 'documentation' => []],
         ]]]);
 
         $this->assertSame($areas, $config['areas']);
@@ -136,6 +136,6 @@ class ConfigurationTest extends TestCase
         $processor = new Processor();
         $config = $processor->processConfiguration(new Configuration(), [['routes' => ['path_patterns' => ['/foo']]]]);
 
-        $this->assertSame(['default' => ['path_patterns' => ['/foo'], 'host_patterns' => []]], $config['areas']);
+        $this->assertSame(['default' => ['path_patterns' => ['/foo'], 'host_patterns' => [], 'documentation' => []]], $config['areas']);
     }
 }

Tests/DependencyInjection/NelmioApiDocExtensionTest.php

@@ -24,8 +24,8 @@ class NelmioApiDocExtensionTest extends TestCase
         $extension = new NelmioApiDocExtension();
         $extension->load([[
             'areas' => [
-                'default' => ['path_patterns' => ['/foo'], 'host_patterns' => []],
+                'default' => ['path_patterns' => ['/foo']],
-                'commercial' => ['path_patterns' => ['/internal'], 'host_patterns' => []],
+                'commercial' => ['path_patterns' => ['/internal']],
             ],
             'models' => [
                 'names' => [

Tests/Functional/FunctionalTest.php

@@ -19,7 +19,8 @@ class FunctionalTest extends WebTestCase
 {
     public function testConfiguredDocumentation()
     {
-        $this->assertEquals('My Test App', $this->getSwaggerDefinition()->getInfo()->getTitle());
+        $this->assertEquals('My Default App', $this->getSwaggerDefinition()->getInfo()->getTitle());
+        $this->assertEquals('My Test App', $this->getSwaggerDefinition('test')->getInfo()->getTitle());
     }
 
     public function testUndocumentedAction()

Tests/Functional/SwaggerUiTest.php

@@ -41,6 +41,7 @@ class SwaggerUiTest extends WebTestCase
         yield ['/docs', 'default', $expected];
 
         // Api-platform documentation
+        $expected['info']['title'] = 'My Test App';
         $expected['paths'] = [
             '/api/dummies' => $expected['paths']['/api/dummies'],
             '/api/foo' => $expected['paths']['/api/foo'],

Tests/Functional/TestKernel.php

@@ -119,7 +119,7 @@ class TestKernel extends Kernel
         $c->loadFromExtension('nelmio_api_doc', [
             'documentation' => [
                 'info' => [
-                    'title' => 'My Test App',
+                    'title' => 'My Default App',
                 ],
                 'definitions' => [
                     'Test' => [
@@ -140,8 +140,19 @@ class TestKernel extends Kernel
                 ],
             ],
            'areas' => [
-               'default' => ['path_patterns' => ['^/api(?!/admin)'], 'host_patterns' => ['^api\.']],
+               'default' => [
-               'test' => ['path_patterns' => ['^/test'], 'host_patterns' => ['^api-test\.']],
+                   'path_patterns' => ['^/api(?!/admin)'],
+                   'host_patterns' => ['^api\.'],
+               ],
+               'test' => [
+                   'path_patterns' => ['^/test'],
+                   'host_patterns' => ['^api-test\.'],
+                   'documentation' => [
+                       'info' => [
+                           'title' => 'My Test App',
+                       ],
+                   ],
+               ],
             ],
         ]);
     }

Tests/Functional/WebTestCase.php

@@ -22,11 +22,11 @@ class WebTestCase extends BaseWebTestCase
         return new TestKernel();
     }
 
-    protected function getSwaggerDefinition()
+    protected function getSwaggerDefinition($area = 'default')
     {
         static::createClient([], ['HTTP_HOST' => 'api.example.com']);
 
-        return static::$kernel->getContainer()->get('nelmio_api_doc.generator')->generate();
+        return static::$kernel->getContainer()->get(sprintf('nelmio_api_doc.generator.%s', $area))->generate();
     }
 
     protected function getModel($name): Schema