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.Readers.Tests/V3Tests/OpenApiDocumentTests.cs

@@ -177,6 +177,85 @@ public async Task ParseMinimalDocumentShouldSucceed()
                 }, result.Diagnostic);
         }
 
+        [Fact]
+        public async Task LoadDocumentWithCircularSchemaPropertyReferencesShouldSucceed()
+        {
+            var filePath = Path.Combine(Path.GetTempPath(), $"{Guid.NewGuid():N}.yaml");
+            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, SettingsFixture.ReaderSettings);
+
+                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 ParseStandardPetStoreDocumentShouldSucceed()
         {