Support use x-* in ref (#1776)

Author: krissss

src/Annotations/OpenApi.php

@@ -219,11 +219,21 @@ private static function resolveRef(string $ref, string $resolved, $container, ar
         $unresolved = $slash === false ? $resolved . $subpath : $resolved . $subpath . '/';
 
         if (is_object($container)) {
-            if (property_exists($container, $property) === false) {
+            // support use x-* in ref
+            $xKey = strpos($property, 'x-') === 0 ? substr($property, 2) : null;
+            if ($xKey) {
+                if (!is_array($container->x) || !array_key_exists($xKey, $container->x)) {
+                    $xKey = null;
+                }
+            }
+            if (property_exists($container, $property) === false && !$xKey) {
                 throw new OpenApiException('$ref "' . $ref . '" not found');
             }
+
+            $nextContainer = $xKey ? $container->x[$xKey] : $container->{$property};
+
             if ($slash === false) {
-                return $container->{$property};
+                return $nextContainer;
             }
             $mapping = [];
             foreach ($container::$_nested as $nestedClass => $nested) {
@@ -232,7 +242,7 @@ private static function resolveRef(string $ref, string $resolved, $container, ar
                 }
             }
 
-            return self::resolveRef($ref, $unresolved, $container->{$property}, $mapping);
+            return self::resolveRef($ref, $unresolved, $nextContainer, $mapping);
         } elseif (is_array($container)) {
             if (array_key_exists($property, $container)) {
                 return self::resolveRef($ref, $unresolved, $container[$property], []);

tests/RefTest.php

@@ -19,9 +19,23 @@ public function testRef(): void
         $this->assertInstanceOf(OA\Info::class, $info);
 
         $comment = <<<END
-@OA\Get(
+@OA\Post(
     path="/api/~/endpoint",
-    @OA\Response(response="default", description="A response")
+    @OA\Response(
+        response="default",
+        description="A response",
+        @OA\JsonContent(ref="#/components/schemas/String/x-custom-key")
+    )
+)
+
+@OA\Schema(
+     schema="String",
+     @OA\Property(property="value", type="string"),
+     x={
+        "custom-key": @OA\Schema(
+            @OA\Property(property="value", type="string"),
+        )
+    }
 )
 END;
         $openapi->merge($this->annotationsFromDocBlockParser($comment));
@@ -32,8 +46,17 @@ public function testRef(): void
         $analysis->validate();
         // escape / as ~1
         // escape ~ as ~0
-        $response = $openapi->ref('#/paths/~1api~1~0~1endpoint/get/responses/default');
+        $response = $openapi->ref('#/paths/~1api~1~0~1endpoint/post/responses/default');
         $this->assertInstanceOf(OA\Response::class, $response);
         $this->assertSame('A response', $response->description);
+
+        // ref x value
+        $schema = $openapi->ref('#/components/schemas/String/x-custom-key');
+        $this->assertInstanceOf(OA\Schema::class, $schema);
+
+        // ref x with deep
+        $property = $openapi->ref('#/components/schemas/String/x-custom-key/properties/value');
+        $this->assertInstanceOf(OA\Property::class, $property);
+        $this->assertSame('string', $property->type);
     }
 }