feat(openapi): allow optional request body content

Author: monitaurus

src/OpenApi/Factory/OpenApiFactory.php

@@ -393,18 +393,26 @@ private function collectPaths(ApiResource $resource, ResourceMetadataCollection
                     'The "openapiContext" option is deprecated, use "openapi" instead.'
                 );
                 $openapiOperation = $openapiOperation->withRequestBody(new RequestBody($contextRequestBody['description'] ?? '', new \ArrayObject($contextRequestBody['content']), $contextRequestBody['required'] ?? false));
-            } elseif (
-                null === $openapiOperation->getRequestBody() && \in_array($method, ['PATCH', 'PUT', 'POST'], true)
+            } else if (
+                \in_array($method, ['PATCH', 'PUT', 'POST'], true)
                 && !(false === ($input = $operation->getInput()) || (\is_array($input) && null === $input['class']))
             ) {
-                $operationInputSchemas = [];
-                foreach ($requestMimeTypes as $operationFormat) {
-                    $operationInputSchema = $this->jsonSchemaFactory->buildSchema($resourceClass, $operationFormat, Schema::TYPE_INPUT, $operation, $schema, null, $forceSchemaCollection);
-                    $operationInputSchemas[$operationFormat] = $operationInputSchema;
-                    $this->appendSchemaDefinitions($schemas, $operationInputSchema->getDefinitions());
+                $content = $openapiOperation->getRequestBody()?->getContent();
+                if (null === $content) {
+                    $operationInputSchemas = [];
+                    foreach ($requestMimeTypes as $operationFormat) {
+                        $operationInputSchema = $this->jsonSchemaFactory->buildSchema($resourceClass, $operationFormat, Schema::TYPE_INPUT, $operation, $schema, null, $forceSchemaCollection);
+                        $operationInputSchemas[$operationFormat] = $operationInputSchema;
+                        $this->appendSchemaDefinitions($schemas, $operationInputSchema->getDefinitions());
+                    }
+                    $content = $this->buildContent($requestMimeTypes, $operationInputSchemas);
                 }
 
-                $openapiOperation = $openapiOperation->withRequestBody(new RequestBody(sprintf('The %s %s resource', 'POST' === $method ? 'new' : 'updated', $resourceShortName), $this->buildContent($requestMimeTypes, $operationInputSchemas), true));
+                $openapiOperation = $openapiOperation->withRequestBody(new RequestBody(
+                    description: $openapiOperation->getRequestBody()?->getDescription() ?? sprintf('The %s %s resource', 'POST' === $method ? 'new' : 'updated', $resourceShortName),
+                    content: $content,
+                    required: $openapiOperation->getRequestBody()?->getRequired() ?? true,
+                ));
             }
 
             // TODO Remove in 4.0
@@ -758,17 +766,17 @@ private function hasParameter(Model\Operation $operation, Parameter $parameter):
     private function mergeParameter(Parameter $actual, Parameter $defined): Parameter
     {
         foreach ([
-            'name',
-            'in',
-            'description',
-            'required',
-            'deprecated',
-            'allowEmptyValue',
-            'style',
-            'explode',
-            'allowReserved',
-            'example',
-        ] as $method) {
+                     'name',
+                     'in',
+                     'description',
+                     'required',
+                     'deprecated',
+                     'allowEmptyValue',
+                     'style',
+                     'explode',
+                     'allowReserved',
+                     'example',
+                 ] as $method) {
             $newValue = $defined->{"get$method"}();
             if (null !== $newValue && $actual->{"get$method"}() !== $newValue) {
                 $actual = $actual->{"with$method"}($newValue);

src/OpenApi/Model/RequestBody.php

@@ -17,16 +17,16 @@ final class RequestBody
 {
     use ExtensionTrait;
 
-    public function __construct(private string $description = '', private ?\ArrayObject $content = null, private bool $required = false)
+    public function __construct(private ?string $description = null, private ?\ArrayObject $content = null, private bool $required = false)
     {
     }
 
-    public function getDescription(): string
+    public function getDescription(): ?string
     {
         return $this->description;
     }
 
-    public function getContent(): \ArrayObject
+    public function getContent(): ?\ArrayObject
     {
         return $this->content;
     }