Defer JsonContent creation to processors; support parameter-level JsonRequestBody

.gitignore

@@ -4,3 +4,4 @@ composer.lock
 coverage/
 vendor/
 .idea/
+/.claude/settings.local.json

README.md

@@ -378,13 +378,21 @@ class LoginRequest
 
 class AuthController
 {
+    // Method-level with explicit ref
     #[OAT\Post(path: '/auth/login', operationId: 'login')]
     #[OAX\JsonRequestBody(ref: LoginRequest::class, required: true)]
     public function login(): mixed
     {
         // description auto-derived as "Login credentials" from schema title
         return '...';
     }
+
+    // Parameter-level — ref inferred from type-hint
+    #[OAT\Post(path: '/auth/register', operationId: 'register')]
+    public function register(#[OAX\JsonRequestBody] LoginRequest $request): mixed
+    {
+        return '...';
+    }
 }
 ```
 
@@ -398,6 +406,24 @@ This is equivalent to the more verbose:
 )]
 ```
 
+When `ref` points to a class with an `#[OAT\RequestBody]` annotation, a component `$ref` is generated instead of inline `JsonContent`:
+
+```php
+#[OAT\RequestBody(request: 'SharedCreateBody')]
+class SharedCreateBody { /* ... */ }
+
+class ItemController
+{
+    #[OAT\Post(path: '/items', operationId: 'createItem')]
+    #[OAX\JsonRequestBody(ref: SharedCreateBody::class)]
+    public function create(): mixed
+    {
+        // produces: $ref: '#/components/requestBodies/SharedCreateBody'
+        return '...';
+    }
+}
+```
+
 
 ## License
 

src/Annotations/JsonRequestBody.php

@@ -21,12 +21,7 @@ public function __construct(array $properties)
         $type = $properties['type'] ?? Generator::UNDEFINED;
         unset($properties['ref'], $properties['type']);
 
-        $resolved = $this->resolveSource($ref, Generator::isDefault($type) ? null : $type);
-
-        if ($resolved['ref'] !== null || $resolved['type'] !== null) {
-            $jsonContent = new OA\JsonContent(array_filter($resolved));
-            $properties['value'] = array_merge($properties['value'] ?? [], [$jsonContent]);
-        }
+        $this->resolveSource($ref, Generator::isDefault($type) ? null : $type);
 
         parent::__construct($properties);
     }

src/Annotations/JsonResponse.php

@@ -21,12 +21,7 @@ public function __construct(array $properties)
         $type = $properties['type'] ?? Generator::UNDEFINED;
         unset($properties['ref'], $properties['type']);
 
-        $resolved = $this->resolveSource($ref, Generator::isDefault($type) ? null : $type);
-
-        if ($resolved['ref'] !== null || $resolved['type'] !== null) {
-            $jsonContent = new OA\JsonContent(array_filter($resolved));
-            $properties['value'] = array_merge($properties['value'] ?? [], [$jsonContent]);
-        }
+        $this->resolveSource($ref, Generator::isDefault($type) ? null : $type);
 
         parent::__construct($properties);
     }

src/Attributes/JsonRequestBody.php

@@ -6,7 +6,7 @@
 use OpenApi\Generator;
 use Radebatz\OpenApi\Extras\JsonContentTrait;
 
-#[\Attribute(\Attribute::TARGET_CLASS | \Attribute::TARGET_METHOD | \Attribute::IS_REPEATABLE)]
+#[\Attribute(\Attribute::TARGET_CLASS | \Attribute::TARGET_METHOD | \Attribute::TARGET_PARAMETER | \Attribute::IS_REPEATABLE)]
 class JsonRequestBody extends OAT\RequestBody
 {
     use JsonContentTrait;
@@ -26,17 +26,12 @@ public function __construct(
         ?array $x = null,
         ?array $attachables = null,
     ) {
-        $resolved = $this->resolveSource($ref, $type);
-
-        $jsonContent = ($resolved['ref'] !== null || $resolved['type'] !== null)
-            ? new OAT\JsonContent(ref: $resolved['ref'], type: $resolved['type'])
-            : null;
+        $this->resolveSource($ref, $type);
 
         parent::__construct(
             request: $request,
             description: $description ?? Generator::UNDEFINED,
             required: $required,
-            content: $jsonContent,
             x: $x,
             attachables: $attachables,
         );

src/Attributes/JsonResponse.php

@@ -27,17 +27,12 @@ public function __construct(
         ?array $x = null,
         ?array $attachables = null,
     ) {
-        $resolved = $this->resolveSource($ref, $type);
-
-        $jsonContent = ($resolved['ref'] !== null || $resolved['type'] !== null)
-            ? new OAT\JsonContent(ref: $resolved['ref'], type: $resolved['type'])
-            : null;
+        $this->resolveSource($ref, $type);
 
         parent::__construct(
             response: $response !== Generator::UNDEFINED ? $response : null,
             description: $description ?? Generator::UNDEFINED,
             headers: $headers,
-            content: $jsonContent,
             x: $x,
             attachables: $attachables,
         );

src/JsonContentTrait.php

@@ -11,23 +11,12 @@ trait JsonContentTrait
 
     public static $_blacklist = ['_context', '_unmerged', '_analysis', 'attachables', 'source'];
 
-    /**
-     * @return array{ref: string|class-string|null, type: string|class-string|null}
-     */
-    protected function resolveSource(string|object $ref, ?string $type): array
+    protected function resolveSource(string|object $ref, ?string $type): void
     {
-        $resolvedRef = null;
-        $resolvedType = null;
-
         if (!Generator::isDefault($ref)) {
-            $resolvedRef = $ref;
             $this->source = $ref;
+        } elseif ($type !== null) {
+            $this->source = $type;
         }
-        if ($type !== null) {
-            $resolvedType = $type;
-            $this->source = $this->source !== Generator::UNDEFINED ? $this->source : $type;
-        }
-
-        return ['ref' => $resolvedRef, 'type' => $resolvedType];
     }
 }

src/Processors/AugmentJsonRequestBody.php

@@ -4,45 +4,67 @@
 
 use OpenApi\Analysis;
 use OpenApi\Annotations as OA;
+use OpenApi\Context;
 use OpenApi\Generator;
 use Radebatz\OpenApi\Extras\Annotations as OAX;
 use Radebatz\OpenApi\Extras\Attributes as OAXT;
+use Radebatz\OpenApi\Extras\Processors\Concerns\ResolvesDescription;
 
 class AugmentJsonRequestBody
 {
+    use ResolvesDescription;
+
     public function __invoke(Analysis $analysis): void
     {
         $requestBodies = $analysis->getAnnotationsOfType([OAX\JsonRequestBody::class, OAXT\JsonRequestBody::class]);
 
         foreach ($requestBodies as $requestBody) {
-            if (!Generator::isDefault($requestBody->description)) {
+            $source = $this->resolveSource($requestBody);
+            if ($source === null) {
                 continue;
             }
 
-            if (!Generator::isDefault($requestBody->source)) {
-                $requestBody->description = $this->resolveDescription($requestBody->source, $analysis);
+            $requestBody->source = $source;
+
+            if (Generator::isDefault($requestBody->content) && Generator::isDefault($requestBody->ref)) {
+                $this->dispatch($requestBody, $source, $analysis);
+            }
+
+            if (Generator::isDefault($requestBody->description)) {
+                $requestBody->description = $this->resolveDescription($source, $analysis);
             }
         }
     }
 
-    protected function resolveDescription(string $source, Analysis $analysis): string
+    protected function resolveSource(OAX\JsonRequestBody|OAXT\JsonRequestBody $requestBody): ?string
     {
-        $schema = $analysis->getAnnotationForSource($source, OA\Schema::class);
+        if (!Generator::isDefault($requestBody->source)) {
+            return $requestBody->source;
+        }
 
-        if ($schema instanceof OA\Schema) {
-            if (!Generator::isDefault($schema->title)) {
-                return $schema->title;
-            }
-            if (!Generator::isDefault($schema->description)) {
-                return $schema->description;
-            }
-            if (!Generator::isDefault($schema->schema)) {
-                return $schema->schema;
+        $reflector = $requestBody->_context->reflector ?? null;
+        if ($reflector instanceof \ReflectionParameter) {
+            $type = $reflector->getType();
+            if ($type instanceof \ReflectionNamedType && !$type->isBuiltin()) {
+                return $type->getName();
             }
         }
 
-        $pos = strrpos($source, '\\');
+        return null;
+    }
+
+    protected function dispatch(OA\RequestBody $requestBody, string $source, Analysis $analysis): void
+    {
+        $sourceRequestBody = $analysis->getAnnotationForSource($source, OA\RequestBody::class);
+        if ($sourceRequestBody instanceof OA\AbstractAnnotation) {
+            $requestBody->ref = OA\Components::ref($sourceRequestBody);
+
+            return;
+        }
+
+        $context = new Context(['nested' => $requestBody], $requestBody->_context);
+        $jsonContent = new OA\JsonContent(['ref' => $source, '_context' => $context]);
 
-        return $pos !== false ? substr($source, $pos + 1) : $source;
+        $analysis->addAnnotation($jsonContent, $context);
     }
 }

src/Processors/AugmentJsonResponse.php

@@ -4,46 +4,40 @@
 
 use OpenApi\Analysis;
 use OpenApi\Annotations as OA;
+use OpenApi\Context;
 use OpenApi\Generator;
 use Radebatz\OpenApi\Extras\Annotations as OAX;
 use Radebatz\OpenApi\Extras\Attributes as OAXT;
+use Radebatz\OpenApi\Extras\Processors\Concerns\ResolvesDescription;
 
 class AugmentJsonResponse
 {
+    use ResolvesDescription;
+
     public function __invoke(Analysis $analysis): void
     {
         $responses = $analysis->getAnnotationsOfType([OAX\JsonResponse::class, OAXT\JsonResponse::class]);
 
         foreach ($responses as $response) {
-            if (!Generator::isDefault($response->description)) {
+            if (Generator::isDefault($response->source)) {
                 continue;
             }
 
-            if (!Generator::isDefault($response->source)) {
+            if (Generator::isDefault($response->content)) {
+                $this->createJsonContent($response, $analysis);
+            }
+
+            if (Generator::isDefault($response->description)) {
                 $response->description = $this->resolveDescription($response->source, $analysis);
             }
         }
     }
 
-    protected function resolveDescription(string $source, Analysis $analysis): string
+    protected function createJsonContent(OAX\JsonResponse|OAXT\JsonResponse $response, Analysis $analysis): void
     {
-        $schema = $analysis->getAnnotationForSource($source, OA\Schema::class);
-
-        if ($schema instanceof OA\Schema) {
-            if (!Generator::isDefault($schema->title)) {
-                return $schema->title;
-            }
-            if (!Generator::isDefault($schema->description)) {
-                return $schema->description;
-            }
-            if (!Generator::isDefault($schema->schema)) {
-                return $schema->schema;
-            }
-        }
-
-        // Fallback to short class name
-        $pos = strrpos($source, '\\');
+        $context = new Context(['nested' => $response], $response->_context);
+        $jsonContent = new OA\JsonContent(['ref' => $response->source, '_context' => $context]);
 
-        return $pos !== false ? substr($source, $pos + 1) : $source;
+        $analysis->addAnnotation($jsonContent, $context);
     }
 }

src/Processors/Concerns/ResolvesDescription.php

@@ -0,0 +1,31 @@
+<?php declare(strict_types=1);
+
+namespace Radebatz\OpenApi\Extras\Processors\Concerns;
+
+use OpenApi\Analysis;
+use OpenApi\Annotations as OA;
+use OpenApi\Generator;
+
+trait ResolvesDescription
+{
+    protected function resolveDescription(string $source, Analysis $analysis): string
+    {
+        $schema = $analysis->getAnnotationForSource($source, OA\Schema::class);
+
+        if ($schema instanceof OA\Schema) {
+            if (!Generator::isDefault($schema->title)) {
+                return $schema->title;
+            }
+            if (!Generator::isDefault($schema->description)) {
+                return $schema->description;
+            }
+            if (!Generator::isDefault($schema->schema)) {
+                return $schema->schema;
+            }
+        }
+
+        $pos = strrpos($source, '\\');
+
+        return $pos !== false ? substr($source, $pos + 1) : $source;
+    }
+}

tests/Fixtures/Controllers/Attributes/ParameterController.php

@@ -0,0 +1,12 @@
+<?php declare(strict_types=1);
+
+namespace Radebatz\OpenApi\Extras\Tests\Fixtures\Controllers\Attributes;
+
+use Radebatz\OpenApi\Extras\Tests\Fixtures\Models\TokenPairResource;
+
+class ParameterController
+{
+    public function create(TokenPairResource $resource): void
+    {
+    }
+}