Support references to config definitions (#1232)

* Support references to config definitions

* Add type hint

* Add a test

Describer/SwaggerPhpDescriber.php

@@ -24,30 +24,31 @@ use Swagger\Annotations as SWG;
 use Swagger\Context;
 use Symfony\Component\Routing\RouteCollection;
 
-final class SwaggerPhpDescriber extends ExternalDocDescriber implements ModelRegistryAwareInterface
+final class SwaggerPhpDescriber implements ModelRegistryAwareInterface
 {
     use ModelRegistryAwareTrait;
 
     private $routeCollection;
-
     private $controllerReflector;
-
     private $annotationReader;
+    private $overwrite;
 
     public function __construct(RouteCollection $routeCollection, ControllerReflector $controllerReflector, Reader $annotationReader, bool $overwrite = false)
     {
         $this->routeCollection = $routeCollection;
         $this->controllerReflector = $controllerReflector;
         $this->annotationReader = $annotationReader;
+        $this->overwrite = $overwrite;
+    }
 
-        parent::__construct(function () {
-            $analysis = $this->getAnnotations();
+    public function describe(Swagger $api)
+    {
+        $analysis = $this->getAnnotations($api);
 
-            $analysis->process($this->getProcessors());
-            $analysis->validate();
+        $analysis->process($this->getProcessors());
+        $analysis->validate();
 
-            return json_decode(json_encode($analysis->swagger), true);
-        }, $overwrite);
+        $api->merge(json_decode(json_encode($analysis->swagger), true), $this->overwrite);
     }
 
     private function getProcessors(): array
@@ -60,9 +61,30 @@ final class SwaggerPhpDescriber extends ExternalDocDescriber implements ModelReg
         return array_merge($processors, Analysis::processors());
     }
 
-    private function getAnnotations(): Analysis
+    private function getAnnotations(Swagger $api): Analysis
     {
         $analysis = new Analysis();
+        $analysis->addAnnotation(new class($api) extends SWG\Swagger {
+            private $api;
+
+            public function __construct(Swagger $api)
+            {
+                $this->api = $api;
+                parent::__construct([]);
+            }
+
+            /**
+             * Support definitions from the config and reference to models.
+             */
+            public function ref($ref)
+            {
+                if (0 === strpos($ref, '#/definitions/') && $this->api->getDefinitions()->has(substr($ref, 14))) {
+                    return;
+                }
+
+                parent::ref($ref);
+            }
+        }, null);
 
         $operationAnnotations = [
             'get' => SWG\Get::class,

Tests/Functional/Controller/ApiController.php

@@ -181,4 +181,16 @@ class ApiController
     public function symfonyConstraintsAction()
     {
     }
+
+    /**
+     * @SWG\Response(
+     *     response="200",
+     *     description="Success",
+     *     @SWG\Schema(ref="#/definitions/Test")
+     * )
+     * @Route("/configReference", methods={"GET"})
+     */
+    public function configReferenceAction()
+    {
+    }
 }

Tests/Functional/FunctionalTest.php

@@ -301,4 +301,10 @@ class FunctionalTest extends WebTestCase
             'type' => 'object',
         ], $this->getModel('SymfonyConstraints')->toArray());
     }
+
+    public function testConfigReference()
+    {
+        $operation = $this->getOperation('/api/configReference', 'get');
+        $this->assertEquals('#/definitions/Test', $operation->getResponses()->get('200')->getSchema()->getRef());
+    }
 }

Tests/Functional/SwaggerUiTest.php

@@ -49,7 +49,7 @@ class SwaggerUiTest extends WebTestCase
                 'responses' => ['200' => ['description' => 'Test']],
             ]],
         ];
-        $expected['definitions'] = ['Dummy' => $expected['definitions']['Dummy']];
+        $expected['definitions'] = ['Dummy' => $expected['definitions']['Dummy'], 'Test' => ['type' => 'string']];
 
         yield ['/docs/test', 'test', $expected];
     }

Tests/Functional/TestKernel.php

@@ -109,6 +109,11 @@ class TestKernel extends Kernel
                 'info' => [
                     'title' => 'My Test App',
                 ],
+                'definitions' => [
+                    'Test' => [
+                        'type' => 'string',
+                    ],
+                ],
             ],
            'areas' => [
                'default' => ['path_patterns' => ['^/api(?!/admin)']],