Resolve relative references before processing

Author: captainsafia

src/OpenApi/src/Services/Schemas/OpenApiSchemaService.cs

@@ -457,5 +457,111 @@ private async Task InnerApplySchemaTransformersAsync(IOpenApiSchema inputSchema,
     }
 
     private JsonNode CreateSchema(OpenApiSchemaKey key)
-        => JsonSchemaExporter.GetJsonSchemaAsNode(_jsonSerializerOptions, key.Type, _configuration);
+    {
+        var schema = JsonSchemaExporter.GetJsonSchemaAsNode(_jsonSerializerOptions, key.Type, _configuration);
+        return ResolveReferences(schema, schema);
+    }
+
+    /// <summary>
+    /// Recursively resolves references within a JSON schema node.
+    /// </summary>
+    private static JsonNode ResolveReferences(JsonNode node, JsonNode rootSchema)
+    {
+        if (node is JsonObject jsonObject)
+        {
+            // Check if this is a reference object
+            if (jsonObject.TryGetPropertyValue("$ref", out var refNode) &&
+                refNode is JsonValue refValue &&
+                refValue.TryGetValue<string>(out var refString) &&
+                refString.StartsWith('#'))
+            {
+                // Resolve the reference path to the actual schema content
+                var resolvedNode = ResolveReference(refString, rootSchema);
+                if (resolvedNode != null)
+                {
+                    // Return a deep clone to avoid parent issues
+                    return resolvedNode.DeepClone();
+                }
+                // If resolution fails, return the original reference
+                return node;
+            }
+
+            // Process all properties recursively
+            var newObject = new JsonObject();
+            foreach (var property in jsonObject)
+            {
+                if (property.Value != null)
+                {
+                    var processedValue = ResolveReferences(property.Value, rootSchema);
+                    // Clone the processed value to avoid parent issues
+                    newObject[property.Key] = processedValue?.DeepClone();
+                }
+                else
+                {
+                    newObject[property.Key] = null;
+                }
+            }
+            return newObject;
+        }
+        else if (node is JsonArray jsonArray)
+        {
+            var newArray = new JsonArray();
+            for (var i = 0; i < jsonArray.Count; i++)
+            {
+                if (jsonArray[i] != null)
+                {
+                    var processedValue = ResolveReferences(jsonArray[i]!, rootSchema);
+                    // Clone the processed value to avoid parent issues
+                    newArray.Add(processedValue?.DeepClone());
+                }
+                else
+                {
+                    newArray.Add(null);
+                }
+            }
+            return newArray;
+        }
+
+        // Return primitive values as-is
+        return node;
+    }
+
+    /// <summary>
+    /// Resolves a JSON reference path (like "#/properties/parent/properties/tags") to the actual schema content.
+    /// </summary>
+    private static JsonNode? ResolveReference(string refPath, JsonNode rootSchema)
+    {
+        // Remove the leading "#" and split the path
+        var path = refPath.TrimStart('#').TrimStart('/');
+        if (string.IsNullOrEmpty(path))
+        {
+            return rootSchema;
+        }
+
+        var segments = path.Split('/');
+        var current = rootSchema;
+
+        foreach (var segment in segments)
+        {
+            if (current is JsonObject currentObject)
+            {
+                if (currentObject.TryGetPropertyValue(segment, out var nextNode) && nextNode != null)
+                {
+                    current = nextNode;
+                }
+                else
+                {
+                    // Path not found
+                    return null;
+                }
+            }
+            else
+            {
+                // Cannot navigate further
+                return null;
+            }
+        }
+
+        return current;
+    }
 }

src/OpenApi/test/Microsoft.AspNetCore.OpenApi.Tests/Integration/snapshots/OpenApi3_0/OpenApiDocumentIntegrationTests.VerifyOpenApiDocument_documentName=schemas-by-ref.verified.txt

@@ -611,7 +611,10 @@
             "$ref": "#/components/schemas/Category"
           },
           "tags": {
-            "$ref": "#/components/schemas/Category/properties/parent/properties/tags"
+            "type": "array",
+            "items": {
+              "$ref": "#/components/schemas/Tag"
+            }
           }
         }
       },
@@ -645,7 +648,10 @@
           "seq2": {
             "type": "array",
             "items": {
-              "$ref": "#/components/schemas/ContainerType/properties/seq1/items"
+              "type": "array",
+              "items": {
+                "type": "string"
+              }
             }
           }
         }
@@ -665,7 +671,10 @@
         "type": "object",
         "properties": {
           "name": {
-            "$ref": "#/components/schemas/Root/properties/item1/properties/name"
+            "type": "array",
+            "items": {
+              "type": "string"
+            }
           },
           "value": {
             "type": "integer",

src/OpenApi/test/Microsoft.AspNetCore.OpenApi.Tests/Integration/snapshots/OpenApi3_1/OpenApiDocumentIntegrationTests.VerifyOpenApiDocument_documentName=schemas-by-ref.verified.txt

@@ -611,7 +611,10 @@
             "$ref": "#/components/schemas/Category"
           },
           "tags": {
-            "$ref": "#/components/schemas/Category/properties/parent/properties/tags"
+            "type": "array",
+            "items": {
+              "$ref": "#/components/schemas/Tag"
+            }
           }
         }
       },
@@ -645,7 +648,10 @@
           "seq2": {
             "type": "array",
             "items": {
-              "$ref": "#/components/schemas/ContainerType/properties/seq1/items"
+              "type": "array",
+              "items": {
+                "type": "string"
+              }
             }
           }
         }
@@ -665,7 +671,10 @@
         "type": "object",
         "properties": {
           "name": {
-            "$ref": "#/components/schemas/Root/properties/item1/properties/name"
+            "type": "array",
+            "items": {
+              "type": "string"
+            }
           },
           "value": {
             "type": "integer",

src/OpenApi/test/Microsoft.AspNetCore.OpenApi.Tests/Integration/snapshots/OpenApiDocumentLocalizationTests.VerifyOpenApiDocumentIsInvariant.verified.txt

@@ -1378,7 +1378,10 @@
             "$ref": "#/components/schemas/Category"
           },
           "tags": {
-            "$ref": "#/components/schemas/Category/properties/parent/properties/tags"
+            "type": "array",
+            "items": {
+              "$ref": "#/components/schemas/Tag"
+            }
           }
         }
       },
@@ -1412,7 +1415,10 @@
           "seq2": {
             "type": "array",
             "items": {
-              "$ref": "#/components/schemas/ContainerType/properties/seq1/items"
+              "type": "array",
+              "items": {
+                "type": "string"
+              }
             }
           }
         }
@@ -1454,7 +1460,10 @@
         "type": "object",
         "properties": {
           "name": {
-            "$ref": "#/components/schemas/Root/properties/item1/properties/name"
+            "type": "array",
+            "items": {
+              "type": "string"
+            }
           },
           "value": {
             "type": "integer",

src/OpenApi/test/Microsoft.AspNetCore.OpenApi.Tests/Transformers/Implementations/OpenApiSchemaReferenceTransformerTests.cs

@@ -740,8 +740,7 @@ await VerifyOpenApiDocument(builder, document =>
             Assert.Equal("Category", ((OpenApiSchemaReference)requestSchema).Reference.Id);
 
             // Assert that $ref is used for nested Tags
-            // Todo: See https://github.com/microsoft/OpenAPI.NET/issues/2062
-            // Assert.Equal("Tag", ((OpenApiSchemaReference)requestSchema.Properties["tags"].Items).Reference.Id);
+            Assert.Equal("Tag", ((OpenApiSchemaReference)requestSchema.Properties["tags"].Items).Reference.Id);
 
             // Assert that $ref is used for nested Parent
             Assert.Equal("Category", ((OpenApiSchemaReference)requestSchema.Properties["parent"]).Reference.Id);