support OpenAPI v3 / zwagger-php 3.x

Author: Tobion

README.md

@@ -8,6 +8,11 @@ Loads routes in Symfony based on [OpenAPI/Swagger annotations](https://github.co
 
     $ composer require tobion/openapi-symfony-routing
 
+Version >= 1.2 requires zircote/swagger-php 3.x which is compatible with the OpenAPI Specification version 3.
+Version < 1.2 requires zircote/swagger-php 2.x which works with the OpenAPI Specification version 2 (fka Swagger).
+So tobion/openapi-symfony-routing can be used with both OpenAPI v2 and v3 and composer will select the compatible one for your dependencies.
+Route loading stays the same between version. You just need to update the annotations when migrating from OpenAPI v2 to v3.
+
 ## Basic Usage
 
 This library allows to (re-)use your OpenAPI documentation to configure the routing of your Symfony-based API.
@@ -16,19 +21,19 @@ This way you do not have to duplicate any routing information in Symfony. Consid
 [zircote/swagger-php](https://github.com/zircote/swagger-php) like the following example:
 
 ```php
-use Swagger\Annotations as SWG;
+use OpenApi\Annotations as OA;
 
 /**
- * @SWG\Swagger(
- *     @SWG\Info(title="My API", version="1.0")
+ * @OA\OpenApi(
+ *     @OA\Info(title="My API", version="1.0")
  * )
  */
 class MyController
 {
     /**
-     * @SWG\Get(
+     * @OA\Get(
      *     path="/foobar",
-     *     @SWG\Response(response="200", description="Success")
+     *     @OA\Response(response="200", description="Success")
      * )
      */
     public function __invoke()
@@ -77,15 +82,15 @@ By default routes are auto-named based on the controller class and method. If yo
 an explicit name, you can do so using the OpenAPI `operationId` property:
 
 ```php
-use Swagger\Annotations as SWG;
+use OpenApi\Annotations as OA;
 
 class MyController
 {
     /**
-     * @SWG\Get(
+     * @OA\Get(
      *     path="/foobar",
      *     operationId="my-name",
-     *     @SWG\Response(response="200", description="Success")
+     *     @OA\Response(response="200", description="Success")
      * )
      */
     public function __invoke()
@@ -102,18 +107,18 @@ The routing loader allows to add a `.{_format}` placeholder automatically to the
 and can be enabled using a `format-suffix` OpenAPI vendor extension:
 
 ```php
-use Swagger\Annotations as SWG;
+use OpenApi\Annotations as OA;
 
 class MyController
 {
     /**
-     * @SWG\Get(
+     * @OA\Get(
      *     path="/foobar",
      *     x={"format-suffix": {
      *         "enabled": true,
      *         "pattern": "json|xml"
      *     }},
-     *     @SWG\Response(response="200", description="Success")
+     *     @OA\Response(response="200", description="Success")
      * )
      */
     public function __invoke()
@@ -123,7 +128,7 @@ class MyController
 ```
 
 The above example will create a route `/foobar.{_format}` where the format is optional and can be json or xml.
-You can also enable the format-suffix globally by configuring it on the root Swagger annotation and disable it for
+You can also enable the format-suffix globally by configuring it on the root OpenApi annotation and disable it for
 certain routes again, see [test fixtures](./tests/Fixtures/FormatSuffix/Controller.php).
 
 ### Order routes with priority
@@ -133,15 +138,15 @@ This can be used to make sure templated routes do not match before concrete rout
 The priority can also be set on OpenAPI annotations using a `priority` vendor extension:
 
 ```php
-use Swagger\Annotations as SWG;
+use OpenApi\Annotations as OA;
 
 class MyController
 {
     /**
-     * @SWG\Get(
+     * @OA\Get(
      *     path="/foobar",
      *     x={"priority": 10},
-     *     @SWG\Response(response="200", description="Success")
+     *     @OA\Response(response="200", description="Success")
      * )
      */
     public function __invoke()

composer.json

@@ -16,7 +16,7 @@
         "symfony/finder": "^4.4|^5.0",
         "symfony/framework-bundle": "^4.4|^5.0",
         "symfony/routing": "^4.4|^5.0",
-        "zircote/swagger-php": "^2.1"
+        "zircote/swagger-php": "^3.0.3"
     },
     "require-dev": {
         "symfony/phpunit-bridge": "^5.2"

src/FormatSuffixConfig.php

@@ -4,7 +4,7 @@
 
 namespace Tobion\OpenApiSymfonyRouting;
 
-use Swagger\Annotations\AbstractAnnotation;
+use OpenApi\Annotations\AbstractAnnotation;
 
 /**
  * @internal

src/OpenApiRouteLoader.php

@@ -4,7 +4,7 @@
 
 namespace Tobion\OpenApiSymfonyRouting;
 
-use Swagger\Annotations\Operation;
+use OpenApi\Annotations\Operation;
 use Symfony\Bundle\FrameworkBundle\Routing\RouteLoaderInterface;
 use Symfony\Component\Finder\Finder;
 use Symfony\Component\Routing\Route;
@@ -44,7 +44,7 @@ public static function fromSrcDirectory(): self
 
     public function __invoke(): RouteCollection
     {
-        $openApi = \Swagger\scan($this->finder);
+        $openApi = \OpenApi\scan($this->finder);
         $routeCollection = new RouteCollection();
 
         $globalFormatSuffixConfig = FormatSuffixConfig::fromAnnotation($openApi);
@@ -66,9 +66,12 @@ public function __invoke(): RouteCollection
         return $routeCollection;
     }
 
-    private function addRouteFromOpenApiOperation(RouteCollection $routeCollection, ?Operation $operation, FormatSuffixConfig $parentFormatSuffixConfig): void
+    /**
+     * @param Operation|string $operation
+     */
+    private function addRouteFromOpenApiOperation(RouteCollection $routeCollection, $operation, FormatSuffixConfig $parentFormatSuffixConfig): void
     {
-        if (null === $operation) {
+        if (\OpenApi\UNDEFINED === $operation || !$operation instanceof Operation) {
             return;
         }
 
@@ -95,10 +98,10 @@ private function createRoute(Operation $operation, string $controller, FormatSuf
                 $route->setRequirement('_format', $formatSuffixConfig->pattern);
             }
         }
-        if (null !== $operation->parameters) {
+        if (\OpenApi\UNDEFINED !== $operation->parameters) {
             foreach ($operation->parameters as $parameter) {
-                if ('path' === $parameter->in && null !== $parameter->pattern) {
-                    $route->setRequirement($parameter->name, $parameter->pattern);
+                if ('path' === $parameter->in && \OpenApi\UNDEFINED !== $parameter->schema && \OpenApi\UNDEFINED !== $parameter->schema->pattern) {
+                    $route->setRequirement($parameter->name, $parameter->schema->pattern);
                 }
             }
         }
@@ -115,7 +118,10 @@ private function getControllerFromOpenApiOperation(Operation $operation): string
 
     private function getRouteName(Operation $operation, string $controller): string
     {
-        return \Swagger\UNDEFINED === $operation->operationId ? $this->getDefaultRouteName($controller) : $operation->operationId;
+        // swagger-php v3 adds the controller as operationId automatically, see \OpenApi\Processors\OperationId.
+        // This must be ignored as it is not viable with multiple annotations on the same controller.
+
+        return \OpenApi\UNDEFINED === $operation->operationId || $controller === $operation->operationId ? $this->getDefaultRouteName($controller) : $operation->operationId;
     }
 
     private function getRoutePriority(Operation $operation): int

tests/Fixtures/Basic/Controller.php

@@ -4,19 +4,19 @@
 
 namespace Tobion\OpenApiSymfonyRouting\Tests\Fixtures\Basic;
 
-use Swagger\Annotations as SWG;
+use OpenApi\Annotations as OA;
 
 /**
- * @SWG\Swagger(
- *     @SWG\Info(title="My API", version="1.0")
+ * @OA\OpenApi(
+ *     @OA\Info(title="My API", version="1.0")
  * )
  */
 class Controller
 {
     /**
-     * @SWG\Get(
+     * @OA\Get(
      *     path="/foobar",
-     *     @SWG\Response(response="200", description="Success")
+     *     @OA\Response(response="200", description="Success")
      * )
      */
     public function __invoke(): void

tests/Fixtures/FormatSuffix/Controller.php

@@ -4,11 +4,11 @@
 
 namespace Tobion\OpenApiSymfonyRouting\Tests\Fixtures\FormatSuffix;
 
-use Swagger\Annotations as SWG;
+use OpenApi\Annotations as OA;
 
 /**
- * @SWG\Swagger(
- *     @SWG\Info(title="My API", version="1.0"),
+ * @OA\OpenApi(
+ *     @OA\Info(title="My API", version="1.0"),
  *     x={"format-suffix": {
  *         "enabled": true
  *     }}
@@ -17,33 +17,33 @@
 class Controller
 {
     /**
-     * @SWG\Get(
+     * @OA\Get(
      *     path="/a",
-     *     @SWG\Response(response="200", description="Success")
+     *     @OA\Response(response="200", description="Success")
      * )
      */
     public function inheritEnabledFormatSuffix(): void
     {
     }
 
     /**
-     * @SWG\Get(
+     * @OA\Get(
      *     path="/b",
      *     x={"format-suffix": {
      *         "pattern": "json|xml"
      *     }},
-     *     @SWG\Response(response="200", description="Success")
+     *     @OA\Response(response="200", description="Success")
      * )
      */
     public function defineFormatPattern(): void
     {
     }
 
     /**
-     * @SWG\Get(
+     * @OA\Get(
      *     path="/c",
      *     x={"format-suffix": false},
-     *     @SWG\Response(response="200", description="Success")
+     *     @OA\Response(response="200", description="Success")
      * )
      */
     public function disableFormatSuffix(): void

tests/Fixtures/OperationId/Controller.php

@@ -4,20 +4,20 @@
 
 namespace Tobion\OpenApiSymfonyRouting\Tests\Fixtures\OperationId;
 
-use Swagger\Annotations as SWG;
+use OpenApi\Annotations as OA;
 
 /**
- * @SWG\Swagger(
- *     @SWG\Info(title="My API", version="1.0")
+ * @OA\OpenApi(
+ *     @OA\Info(title="My API", version="1.0")
  * )
  */
 class Controller
 {
     /**
-     * @SWG\Get(
+     * @OA\Get(
      *     path="/foobar",
      *     operationId="my-name",
-     *     @SWG\Response(response="200", description="Success")
+     *     @OA\Response(response="200", description="Success")
      * )
      */
     public function __invoke(): void

tests/Fixtures/PathParameterPattern/Controller.php

@@ -4,42 +4,56 @@
 
 namespace Tobion\OpenApiSymfonyRouting\Tests\Fixtures\PathParameterPattern;
 
-use Swagger\Annotations as SWG;
+use OpenApi\Annotations as OA;
 
 /**
- * @SWG\Swagger(
- *     @SWG\Info(title="My API", version="1.0")
+ * @OA\OpenApi(
+ *     @OA\Info(title="My API", version="1.0")
  * )
  */
 class Controller
 {
     /**
-     * @SWG\Get(
+     * @OA\Get(
      *     path="/foo/{id}",
-     *     @SWG\Parameter(
+     *     @OA\Parameter(
      *         name="id",
      *         in="path",
-     *         type="string",
-     *         required=true
+     *         required=true,
+     *         @OA\Schema(type="string")
      *     ),
-     *     @SWG\Response(response="200", description="Success")
+     *     @OA\Response(response="200", description="Success")
      * )
      */
     public function noPattern(): void
     {
     }
 
     /**
-     * @SWG\Get(
+     * @OA\Get(
+     *     path="/baz/{id}",
+     *     @OA\Parameter(
+     *         name="id",
+     *         in="path",
+     *         required=true
+     *     ),
+     *     @OA\Response(response="200", description="Success")
+     * )
+     */
+    public function noSchema(): void
+    {
+    }
+
+    /**
+     * @OA\Get(
      *     path="/bar/{id}",
-     *     @SWG\Parameter(
+     *     @OA\Parameter(
      *         name="id",
      *         in="path",
-     *         type="string",
      *         required=true,
-     *         pattern="^[a-zA-Z0-9]+$"
+     *         @OA\Schema(type="string", pattern="^[a-zA-Z0-9]+$")
      *     ),
-     *     @SWG\Response(response="200", description="Success")
+     *     @OA\Response(response="200", description="Success")
      * )
      */
     public function withPattern(): void