fix(library): handle circular schema references

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

Author: baywet

src/Microsoft.OpenApi/Models/References/BaseOpenApiReferenceHolder.cs

@@ -1,4 +1,5 @@
 using System;
+using System.Collections.Generic;
 
 namespace Microsoft.OpenApi;
 /// <summary>
@@ -23,13 +24,24 @@ public T? RecursiveTarget
     {
         get
         {
-            return Target switch {
-                BaseOpenApiReferenceHolder<T, U, V> recursiveTarget => recursiveTarget.RecursiveTarget,
-                T concrete => concrete,
-                _ => null
-            };
+            return ResolveRecursiveTarget(new HashSet<BaseOpenApiReferenceHolder<T, U, V>>());
         }
     }
+
+    private T? ResolveRecursiveTarget(ISet<BaseOpenApiReferenceHolder<T, U, V>> visitedReferences)
+    {
+        if (!visitedReferences.Add(this))
+        {
+            throw new InvalidOperationException($"Circular reference detected while resolving reference: {Reference.ReferenceV3}");
+        }
+
+        return Target switch
+        {
+            BaseOpenApiReferenceHolder<T, U, V> recursiveTarget => recursiveTarget.ResolveRecursiveTarget(visitedReferences),
+            T concrete => concrete,
+            _ => null
+        };
+    }
     /// <summary>
     /// Copy the reference as a target element with overrides.
     /// </summary>

src/Microsoft.OpenApi/Services/OpenApiWalker.cs

@@ -904,11 +904,17 @@ internal void Walk(OpenApiEncoding encoding)
         /// </summary>
         internal void Walk(IOpenApiSchema? schema, bool isComponent = false)
         {
-            if (schema == null || schema is IOpenApiReferenceHolder holder && ProcessAsReference(holder, isComponent))
+            if (schema == null)
             {
                 return;
             }
 
+            if (schema is IOpenApiReferenceHolder holder)
+            {
+                Walk(holder);
+                return;
+            }
+
             if (_schemaLoop.Contains(schema))
             {
                 return;  // Loop detected, this schema has already been walked.
@@ -1353,19 +1359,6 @@ private void WalkDictionary<T>(
             }
         }
 
-        /// <summary>
-        /// Identify if an element is just a reference to a component, or an actual component
-        /// </summary>
-        private bool ProcessAsReference(IOpenApiReferenceHolder referenceableHolder, bool isComponent = false)
-        {
-            var isReference = !isComponent || referenceableHolder.UnresolvedReference;
-            if (isReference)
-            {
-                Walk(referenceableHolder);
-            }
-            return isReference;
-        }
-
         private void WalkTags<T>(ISet<T> tags, Action<OpenApiWalker, T> walk)
             where T : IOpenApiTag
         {

test/Microsoft.OpenApi.Tests/Reader/OpenApiModelFactoryTests.cs

@@ -9,6 +9,96 @@ namespace Microsoft.OpenApi.Tests.Reader;
 
 public class OpenApiModelFactoryTests
 {
+    [Fact]
+    public async Task LoadDocumentWithCircularSchemaPropertyReferencesShouldSucceed()
+    {
+        var filePath = Path.Combine(Path.GetTempPath(), $"{Guid.NewGuid():N}.json");
+        await File.WriteAllTextAsync(filePath, """
+{
+    "openapi": "3.0.0",
+    "info": {
+        "title": "Test",
+        "version": "0.0.1"
+    },
+    "paths": {},
+    "components": {
+        "schemas": {
+            "A": {
+                "properties": {
+                    "b": {
+                        "$ref": "#/components/schemas/B"
+                    }
+                }
+            },
+            "B": {
+                "properties": {
+                    "a": {
+                        "$ref": "#/components/schemas/A"
+                    }
+                }
+            }
+        }
+    }
+}
+""");
+
+        try
+        {
+            var result = await OpenApiDocument.LoadAsync(filePath);
+
+            Assert.NotNull(result.Document);
+            Assert.Empty(result.Diagnostic.Errors);
+
+            var schemaA = Assert.IsType<OpenApiSchema>(result.Document.Components.Schemas["A"]);
+            var schemaBReference = Assert.IsType<OpenApiSchemaReference>(schemaA.Properties["b"]);
+            Assert.Same(result.Document.Components.Schemas["B"], schemaBReference.Target);
+        }
+        finally
+        {
+            File.Delete(filePath);
+        }
+    }
+
+    [Fact]
+    public async Task LoadDocumentWithCircularRootSchemaReferencesShouldReturnDiagnosticWarning()
+    {
+        var filePath = Path.Combine(Path.GetTempPath(), $"{Guid.NewGuid():N}.json");
+        await File.WriteAllTextAsync(filePath, """
+{
+    "openapi": "3.0.0",
+    "info": {
+        "title": "Test",
+        "version": "0.0.1"
+    },
+    "paths": {},
+    "components": {
+        "schemas": {
+            "A": {
+                "$ref": "#/components/schemas/B"
+            },
+            "B": {
+                "$ref": "#/components/schemas/A"
+            }
+        }
+    }
+}
+""");
+
+        try
+        {
+            var result = await OpenApiDocument.LoadAsync(filePath);
+
+            Assert.NotNull(result.Document);
+            Assert.Empty(result.Diagnostic.Errors);
+            Assert.Contains(result.Diagnostic.Warnings,
+                warning => warning.Message.StartsWith("Circular reference detected while resolving reference:", StringComparison.Ordinal));
+        }
+        finally
+        {
+            File.Delete(filePath);
+        }
+    }
+
     [Fact]
     public async Task UsesSettingsBaseUrl()
     {