Update docs with OpenApiFactoryInterface. (#1342)

Author: alexsegura

core/openapi.md

@@ -69,15 +69,16 @@ use ApiPlatform\Core\OpenApi\Factory\OpenApiFactoryInterface;
 use ApiPlatform\Core\OpenApi\OpenApi;
 use ApiPlatform\Core\OpenApi\Model;
 
-class OpenApiFactory implements OpenApiFactoryInterface {
+class OpenApiFactory implements OpenApiFactoryInterface
+{
     private $decorated;
 
-    public function __construct(OpenApiFactoryInterface $decorated) 
+    public function __construct(OpenApiFactoryInterface $decorated)
     {
         $this->decorated = $decorated;
     }
 
-    public function __invoke(array $context = []): OpenApi 
+    public function __invoke(array $context = []): OpenApi
     {
         $openApi = $this->decorated->__invoke($context);
         $pathItem = $openApi->getPaths()->getPath('/api/grumpy_pizzas/{id}');
@@ -163,7 +164,7 @@ class Product // The class name will be used to name exposed resources
      * )
      */
     public $timestamp;
-    
+
     // ...
 }
 ```
@@ -539,7 +540,7 @@ The [info object](https://swagger.io/specification/#info-object) provides metada
 
 ```yaml
 api_platform:
-    
+
     # The title of the API.
     title: 'API title'
 
@@ -548,7 +549,7 @@ api_platform:
 
     # The version of the API.
     version: '0.0.0'
-    
+
     openapi:
         # The contact information for the exposed API.
         contact:
@@ -565,5 +566,5 @@ api_platform:
             # The license name used for the API.
             name:
             # URL to the license used for the API. MUST be in the format of a URL.
-            url: 
+            url:
 ```

core/operations.md

@@ -422,7 +422,7 @@ class CreateBookPublication
     public function __construct(
         private BookPublishingHandler $bookPublishingHandler
     ) {}
-    
+
     #[Route(
         path: '/books/{id}/publication',
         name: 'book_post_publication',
@@ -620,34 +620,46 @@ class Weather
 This way, we expose a route that will do… nothing. Note that the controller does not even need to exist.
 
 It's almost done, we have just one final issue: our fake item operation is visible in the API docs.
-To remove it, we will need to [decorate the Swagger documentation](swagger.md#overriding-the-openapi-specification).
+To remove it, we will need to [decorate the Swagger documentation](openapi.md#overriding-the-openapi-specification).
 Then, remove the route from the decorator:
 
 ```php
 <?php
-// src/Swagger/SwaggerDecorator.php
+// src/OpenApi/OpenApiFactory.php
 
-namespace App\Swagger;
+namespace App\OpenApi;
 
-use Symfony\Component\Serializer\Normalizer\NormalizerInterface;
+use ApiPlatform\Core\OpenApi\Factory\OpenApiFactoryInterface;
+use ApiPlatform\Core\OpenApi\OpenApi;
+use ApiPlatform\Core\OpenApi\Model;
 
-final class SwaggerDecorator implements NormalizerInterface
+final class OpenApiFactory implements OpenApiFactoryInterface
 {
-    public function __construct(
-        private NormalizerInterface $decorated
-    ) {}
+    private $decorated;
+
+    public function __construct(OpenApiFactoryInterface $decorated)
+    {
+        $this->decorated = $decorated;
+    }
 
-    public function normalize($object, string $format = null, array $context = [])
+    public function __invoke(array $context = []): OpenApi
     {
-        $docs = $this->decorated->normalize($object, $format, $context);
+        $openApi = $this->decorated->__invoke($context);
 
-        // If a prefix is configured on API Platform's routes, it must appear here.
-        unset($docs['paths']['/weathers/{id}']);
+        $paths = $openApi->getPaths()->getPaths();
 
-        return $docs;
-    }
+        $filteredPaths = new Model\Paths();
+        foreach ($paths as $path => $pathItem) {
+            // If a prefix is configured on API Platform's routes, it must appear here.
+            if ($path === '/weathers/{id}') {
+                continue;
+            }
+            $filteredPaths->addPath($path, $pathItem);
+        }
 
-    // ...
+        return $openApi->withPaths($filteredPaths);
+    }
+}
 ```
 
 That's it: your route is gone!