allow format-suffix to be specified on any part of the openapi

so the config can be inherited which allows to change it globally or for different paths

Author: Tobion

src/FormatSuffixConfig.php

@@ -0,0 +1,47 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Tobion\OpenApiSymfonyRouting;
+
+use Swagger\Annotations\AbstractAnnotation;
+
+/**
+ * @internal
+ */
+class FormatSuffixConfig
+{
+    /**
+     * @var bool
+     */
+    public $enabled;
+
+    /**
+     * @var string|null
+     */
+    public $pattern;
+
+    public function __construct(
+        bool $enabled,
+        ?string $pattern
+    ) {
+        $this->enabled = $enabled;
+        $this->pattern = $pattern;
+    }
+
+    public static function fromAnnotation(AbstractAnnotation $annotation, ?self $parent = null): self
+    {
+        if (!isset($annotation->x['format-suffix'])) {
+            return new self($parent ? $parent->enabled : false, $parent ? $parent->pattern : null);
+        }
+
+        if (is_bool($annotation->x['format-suffix'])) {
+            return new self($annotation->x['format-suffix'], $parent ? $parent->pattern : null);
+        }
+
+        return new self(
+            $annotation->x['format-suffix']['enabled'] ?? ($parent ? $parent->enabled : false),
+            $annotation->x['format-suffix']['pattern'] ?? ($parent ? $parent->pattern : null)
+        );
+    }
+}

src/OpenApiRouteLoader.php

@@ -17,25 +17,13 @@ class OpenApiRouteLoader implements RouteLoaderInterface
      */
     private $finder;
 
-    /**
-     * @var bool
-     */
-    private $addFormatSuffix;
-
-    /**
-     * @var string|null
-     */
-    private $defaultFormatPattern;
-
     /**
      * @var array<string, int>
      */
     private $routeNames = [];
 
     public function __construct(
-        ?Finder $finder = null,
-        bool $addFormatSuffix = false,
-        ?string $defaultFormatPattern = null
+        ?Finder $finder = null
     ) {
         if (null === $finder) {
             // try to use the symfony flex default src directory based on a composer install
@@ -49,55 +37,58 @@ public function __construct(
         }
 
         $this->finder = $finder;
-        $this->addFormatSuffix = $addFormatSuffix;
-        $this->defaultFormatPattern = $defaultFormatPattern;
     }
 
     public function __invoke(): RouteCollection
     {
         $fullSwagger = \Swagger\scan($this->finder);
         $routeCollection = new RouteCollection();
 
+        $globalFormatSuffixConfig = FormatSuffixConfig::fromAnnotation($fullSwagger);
+
         foreach ($fullSwagger->paths as $path) {
-            $this->addRouteFromSwaggerOperation($routeCollection, $path->get);
-            $this->addRouteFromSwaggerOperation($routeCollection, $path->put);
-            $this->addRouteFromSwaggerOperation($routeCollection, $path->post);
-            $this->addRouteFromSwaggerOperation($routeCollection, $path->delete);
-            $this->addRouteFromSwaggerOperation($routeCollection, $path->options);
-            $this->addRouteFromSwaggerOperation($routeCollection, $path->head);
-            $this->addRouteFromSwaggerOperation($routeCollection, $path->patch);
+            $pathFormatSuffixConfig = FormatSuffixConfig::fromAnnotation($path, $globalFormatSuffixConfig);
+
+            $this->addRouteFromSwaggerOperation($routeCollection, $path->get, $pathFormatSuffixConfig);
+            $this->addRouteFromSwaggerOperation($routeCollection, $path->put, $pathFormatSuffixConfig);
+            $this->addRouteFromSwaggerOperation($routeCollection, $path->post, $pathFormatSuffixConfig);
+            $this->addRouteFromSwaggerOperation($routeCollection, $path->delete, $pathFormatSuffixConfig);
+            $this->addRouteFromSwaggerOperation($routeCollection, $path->options, $pathFormatSuffixConfig);
+            $this->addRouteFromSwaggerOperation($routeCollection, $path->head, $pathFormatSuffixConfig);
+            $this->addRouteFromSwaggerOperation($routeCollection, $path->patch, $pathFormatSuffixConfig);
         }
 
         $this->routeNames = [];
 
         return $routeCollection;
     }
 
-    private function addRouteFromSwaggerOperation(RouteCollection $routeCollection, ?Operation $operation): void
+    private function addRouteFromSwaggerOperation(RouteCollection $routeCollection, ?Operation $operation, FormatSuffixConfig $parentFormatSuffixConfig): void
     {
         if (null === $operation) {
             return;
         }
 
         $controller = $this->getControllerFromSwaggerOperation($operation);
         $name = $this->getRouteName($operation, $controller);
-        $route = $this->createRoute($operation, $controller);
+        $route = $this->createRoute($operation, $controller, $parentFormatSuffixConfig);
         $routeCollection->add($name, $route);
     }
 
-    private function createRoute(Operation $operation, string $controller): Route
+    private function createRoute(Operation $operation, string $controller, FormatSuffixConfig $parentFormatSuffixConfig): Route
     {
-        $formatSuffix = $operation->x['format-suffix'] ?? $this->addFormatSuffix;
-        $path = $formatSuffix ? $operation->path.'.{_format}' : $operation->path;
+        $formatSuffixConfig = FormatSuffixConfig::fromAnnotation($operation, $parentFormatSuffixConfig);
+
+        $path = $formatSuffixConfig->enabled ? $operation->path.'.{_format}' : $operation->path;
         $route = new Route($path);
         $route->setMethods($operation->method);
         $route->setDefault('_controller', $controller);
-        if ($formatSuffix) {
-            $formatPattern = $operation->x['format-pattern'] ?? $this->defaultFormatPattern;
+
+        if ($formatSuffixConfig->enabled) {
             $route->setDefault('_format', null);
 
-            if (null !== $formatPattern) {
-                $route->setRequirement('_format', $formatPattern);
+            if (null !== $formatSuffixConfig->pattern) {
+                $route->setRequirement('_format', $formatSuffixConfig->pattern);
             }
         }
         if (null !== $operation->parameters) {

tests/Fixtures/FormatSuffix/Controller.php

@@ -11,7 +11,10 @@
  *     @SWG\Info(
  *         title="My API",
  *         version="1.0"
- *     )
+ *     ),
+ *     x={"format-suffix": {
+ *         "enabled": true
+ *     }}
  * )
  */
 class Controller
@@ -32,7 +35,9 @@ public function inheritEnabledFormatSuffix(): void
     /**
      * @SWG\Get(
      *     path="/b",
-     *     x={"format-pattern": "json|xml"},
+     *     x={"format-suffix": {
+     *         "pattern": "json|xml"
+     *     }},
      *     @SWG\Response(
      *         response="200",
      *         description="Success",

tests/OpenApiRouteLoaderTest.php

@@ -42,7 +42,7 @@ public function testBasic(): void
     public function testFormatSuffix(): void
     {
         $finder = (new Finder())->in(__DIR__.'/Fixtures/FormatSuffix');
-        $routeLoader = new OpenApiRouteLoader($finder, true);
+        $routeLoader = new OpenApiRouteLoader($finder);
 
         $routes = $routeLoader->__invoke();