Refactor Existing Ref parsing in RouteMetadataDescriber

RouteDescriber/RouteMetadataDescriber.php

@@ -11,7 +11,10 @@
 
 namespace Nelmio\ApiDocBundle\RouteDescriber;
 
+use EXSyst\Component\Swagger\Operation;
+use EXSyst\Component\Swagger\Parameter;
 use EXSyst\Component\Swagger\Swagger;
+use LogicException;
 use Symfony\Component\Routing\Route;
 
 /**
@@ -28,29 +31,7 @@ final class RouteMetadataDescriber implements RouteDescriberInterface
 
             $requirements = $route->getRequirements();
             $compiledRoute = $route->compile();
-
+            $existingParams = $this->getRefParams($api, $operation);
-            $globalParams = $api->getParameters();
-            $existingParams = [];
-            foreach ($operation->getParameters() as $id => $parameter) {
-                $ref = $parameter->getRef();
-                if (null === $ref) {
-                    $existingParams[$id] = true;
-
-                    // we only concern ourselves with '$ref' parameters
-                    continue;
-                }
-
-                $ref = \mb_substr($ref, 13); // trim the '#/parameters/' part of ref
-                if (!isset($globalParams[$ref])) {
-                    // this shouldn't happen, so just ignore here
-                    continue;
-                }
-
-                $refParameter = $globalParams[$ref];
-
-                // param ids are in form {name}/{in}
-                $existingParams[\sprintf('%s/%s', $refParameter->getName(), $refParameter->getIn())] = true;
-            }
 
             // Don't include host requirements
             foreach ($compiledRoute->getPathVariables() as $pathVariable) {
@@ -58,8 +39,14 @@ final class RouteMetadataDescriber implements RouteDescriberInterface
                     continue;
                 }
 
-                if (isset($existingParams[$pathVariable.'/path'])) {
+                $paramId = $pathVariable.'/path';
-                    continue; // ignore this param, it is already defined
+                $parameter = $existingParams[$paramId] ?? null;
+                if (null !== $parameter) {
+                    if (!$parameter->getRequired()) {
+                        throw new LogicException(\sprintf('Global parameter "%s" is used as part of route "%s" and must be set as "required"', $pathVariable, $route->getPath()));
+                    }
+
+                    continue;
                 }
 
                 $parameter = $operation->getParameters()->get($pathVariable, 'path');
@@ -75,4 +62,37 @@ final class RouteMetadataDescriber implements RouteDescriberInterface
             }
         }
     }
+
+    /**
+     * The '$ref' parameters need special handling, since their objects are missing 'name' and 'in'.
+     *
+     * @return Parameter[] existing $ref parameters
+     */
+    private function getRefParams(Swagger $api, Operation $operation): array
+    {
+        /** @var Parameter[] $globalParams */
+        $globalParams = $api->getParameters();
+        $existingParams = [];
+
+        foreach ($operation->getParameters() as $id => $parameter) {
+            $ref = $parameter->getRef();
+            if (null === $ref) {
+                // we only concern ourselves with '$ref' parameters, so continue the loop
+                continue;
+            }
+
+            $ref = \mb_substr($ref, 13); // trim the '#/parameters/' part of ref
+            if (!isset($globalParams[$ref])) {
+                // this shouldn't happen during proper configs, but in case of bad config, just ignore it here
+                continue;
+            }
+
+            $refParameter = $globalParams[$ref];
+
+            // param ids are in form {name}/{in}
+            $existingParams[\sprintf('%s/%s', $refParameter->getName(), $refParameter->getIn())] = $refParameter;
+        }
+
+        return $existingParams;
+    }
 }

Tests/Functional/Controller/TestController.php

@@ -29,4 +29,16 @@ class TestController
     public function testAction()
     {
     }
+
+    /**
+     * @SWG\Parameter(ref="#/parameters/test"),
+     * @SWG\Response(
+     *     response="200",
+     *     description="Test Ref"
+     * )
+     * @Route("/test/{id}", methods={"GET"})
+     */
+    public function testRefAction()
+    {
+    }
 }

Tests/Functional/SwaggerUiTest.php

@@ -59,6 +59,10 @@ class SwaggerUiTest extends WebTestCase
             '/test/test/' => ['get' => [
                 'responses' => ['200' => ['description' => 'Test']],
             ]],
+            '/test/test/{id}' => ['get' => [
+                'responses' => ['200' => ['description' => 'Test Ref']],
+                'parameters' => [['$ref' => '#/parameters/test']],
+            ]],
         ];
         $expected['definitions'] = [
             'Dummy' => $expected['definitions']['Dummy'],