docs: document openapi object argument (#1679)

Author: vincentchalamon

core/file-upload.md

@@ -60,6 +60,7 @@ use ApiPlatform\Metadata\ApiResource;
 use ApiPlatform\Metadata\Get;
 use ApiPlatform\Metadata\GetCollection;
 use ApiPlatform\Metadata\Post;
+use ApiPlatform\OpenApi\Model;
 use App\Controller\CreateMediaObjectAction;
 use Doctrine\ORM\Mapping as ORM;
 use Symfony\Component\HttpFoundation\File\File;
@@ -79,9 +80,9 @@ use Vich\UploaderBundle\Mapping\Annotation as Vich;
             controller: CreateMediaObjectAction::class, 
             deserialize: false, 
             validationContext: ['groups' => ['Default', 'media_object_create']], 
-            openapiContext: [
-                'requestBody' => [
-                    'content' => [
+            openapi: new Model\Operation(
+                requestBody: new Model\RequestBody(
+                    content: new \ArrayObject([
                         'multipart/form-data' => [
                             'schema' => [
                                 'type' => 'object', 
@@ -93,9 +94,9 @@ use Vich\UploaderBundle\Mapping\Annotation as Vich;
                                 ]
                             ]
                         ]
-                    ]
-                ]
-            ]
+                    ])
+                )
+            )
         )
     ]
 )]

core/openapi.md

@@ -304,18 +304,19 @@ namespace App\Entity;
 
 use ApiPlatform\Metadata\ApiResource;
 use ApiPlatform\Metadata\Post;
+use ApiPlatform\OpenApi\Model;
 use App\Controller\RandomRabbit;
 
 #[ApiResource]
 #[Post(
     name: 'create_rabbit', 
     uriTemplate: '/rabbit/create', 
     controller: RandomRabbit::class, 
-    openapiContext: [
-        'summary' => 'Create a rabbit picture', 
-        'description' => '# Pop a great rabbit picture by color!\n\n![A great rabbit](https://rabbit.org/graphics/fun/netbunnies/jellybean1-brennan1.jpg)', 
-        'requestBody' => [
-            'content' => [
+    openapi: new Model\Operation(
+        summary: 'Create a rabbit picture', 
+        description: '# Pop a great rabbit picture by color!\n\n![A great rabbit](https://rabbit.org/graphics/fun/netbunnies/jellybean1-brennan1.jpg)', 
+        requestBody: new Model\RequestBody(
+            content: new \ArrayObject([
                 'application/json' => [
                     'schema' => [
                         'type' => 'object', 
@@ -329,9 +330,9 @@ use App\Controller\RandomRabbit;
                         'description' => 'Pink Rabbit'
                     ]
                 ]
-            ]
-        ]
-    ]
+            ])
+        )
+    )
 )]
 class Rabbit
 {
@@ -347,7 +348,7 @@ resources:
         class: ApiPlatform\Metadata\Post
         path: '/rabbit/create'
         controller: App\Controller\RandomRabbit
-        openapiContext:
+        openapi:
           summary: Random rabbit picture
           description: >
             # Pop a great rabbit picture by color!
@@ -378,7 +379,7 @@ resources:
         <operations>
             <operation class="ApiPlatform\Metadata\Post" name="create_rabbit" uriTemplate="/rabbit/create"
                        controller="App\Controller\RandomRabbit">
-                <openapiContext>
+                <openapi>
                     <values>
                         <value name="summary">Create a rabbit picture </value>
                         <value name="description"># Pop a great rabbit picture by color!!
@@ -412,7 +413,7 @@ resources:
                             </values>
                         </value>
                     </values>
-                </openapiContext>
+                </openapi>
             </operation>
         </operations>
     </resource>