Allow FAQN in $ref

src/Processors/AugmentProperties.php

@@ -17,6 +17,7 @@
 class AugmentProperties implements ProcessorInterface
 {
     use Concerns\DocblockTrait;
+    use Concerns\RefTrait;
     use Concerns\TypesTrait;
 
     public function __invoke(Analysis $analysis)
@@ -67,13 +68,6 @@ public function __invoke(Analysis $analysis)
         }
     }
 
-    protected function toRefKey(Context $context, ?string $name): string
-    {
-        $fqn = strtolower($context->fullyQualifiedName($name));
-
-        return ltrim($fqn, '\\');
-    }
-
     protected function augmentType(Analysis $analysis, OA\Property $property, Context $context, array $refs, array $varMatches): void
     {
         // docblock typehints

src/Processors/AugmentRefs.php

@@ -10,12 +10,20 @@
 use OpenApi\Annotations as OA;
 use OpenApi\Generator;
 
-/**
- * Update refs broken due to `allOf` augmenting.
- */
 class AugmentRefs implements ProcessorInterface
 {
+    use Concerns\RefTrait;
+
     public function __invoke(Analysis $analysis)
+    {
+        $this->resolveAllOfRefs($analysis);
+        $this->resolveFQCNRefs($analysis);
+    }
+
+    /**
+     * Update refs broken due to `allOf` augmenting.
+     */
+    protected function resolveAllOfRefs(Analysis $analysis)
     {
         /** @var OA\Schema[] $schemas */
         $schemas = $analysis->getAnnotationsOfType(OA\Schema::class);
@@ -46,4 +54,19 @@ public function __invoke(Analysis $analysis)
             }
         }
     }
+
+    protected function resolveFQCNRefs(Analysis $analysis)
+    {
+        /** @var OA\AbstractAnnotation[] $annotations */
+        $annotations = $analysis->getAnnotationsOfType([OA\Examples::class, OA\Header::class, OA\Link::class, OA\Parameter::class, OA\PathItem::class, OA\RequestBody::class, OA\Response::class, OA\Schema::class, OA\SecurityScheme::class]);
+
+        foreach ($annotations as $annotation) {
+            if (property_exists($annotation, 'ref') && !Generator::isDefault($annotation->ref) && is_string($annotation->ref) && !$this->isRef($annotation->ref)) {
+                // check if we have a schema for this
+                if ($refSchema = $analysis->getSchemaForSource($annotation->ref)) {
+                    $annotation->ref = OA\Components::ref($refSchema);
+                }
+            }
+        }
+    }
 }

src/Processors/Concerns/RefTrait.php

@@ -0,0 +1,24 @@
+<?php declare(strict_types=1);
+
+/**
+ * @license Apache 2.0
+ */
+
+namespace OpenApi\Processors\Concerns;
+
+use OpenApi\Context;
+
+trait RefTrait
+{
+    protected function toRefKey(Context $context, ?string $name): string
+    {
+        $fqn = strtolower($context->fullyQualifiedName($name));
+
+        return ltrim($fqn, '\\');
+    }
+
+    protected function isRef(?string $ref): bool
+    {
+        return $ref && 0 === strpos($ref, '#/');
+    }
+}

tests/Fixtures/Scratch/ClassRef.php

@@ -0,0 +1,29 @@
+<?php declare(strict_types=1);
+
+/**
+ * @license Apache 2.0
+ */
+
+namespace OpenApi\Tests\Fixtures\Scratch;
+
+use OpenApi\Attributes as OAT;
+
+#[OAT\Schema(schema: 'YoYo')]
+class ClassRef
+{
+}
+
+#[OAT\Info(title: 'ClassRef', version: '1.0')]
+#[OAT\Get(
+    path: '/endpoint',
+    responses: [
+        new OAT\Response(
+            response: 200,
+            description: 'All good',
+            content: new OAT\JsonContent(ref: ClassRef::class)
+        ),
+    ]
+)]
+class ClassRefEndpoint
+{
+}

tests/Fixtures/Scratch/ClassRef.yaml

@@ -0,0 +1,17 @@
+openapi: 3.0.0
+info:
+  title: ClassRef
+  version: '1.0'
+paths:
+  /endpoint:
+    get:
+      responses:
+        '200':
+          description: 'All good'
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/YoYo'
+components:
+  schemas:
+    YoYo: {  }