Added support for handling cycles

Author: darrelmiller

src/Microsoft.OpenApi/Models/OpenApiComponents.cs

@@ -1,7 +1,9 @@
 // Copyright (c) Microsoft Corporation. All rights reserved.
 // Licensed under the MIT license. 
 
+using System;
 using System.Collections.Generic;
+using System.Linq;
 using Microsoft.OpenApi.Any;
 using Microsoft.OpenApi.Interfaces;
 using Microsoft.OpenApi.Writers;
@@ -77,9 +79,23 @@ public void SerializeAsV3(IOpenApiWriter writer)
             }
 
             // If references have been inlined we don't need the to render the components section
+            // however if they have cycles, then we will need a component rendered
             if (writer.GetSettings().ReferenceInline != ReferenceInlineSetting.DoNotInlineReferences)
             {
+                var loops = writer.GetSettings().LoopDetector.Loops;
                 writer.WriteStartObject();
+                if (loops.TryGetValue(typeof(OpenApiSchema), out List<object> schemas))
+                {
+                    var openApiSchemas = schemas.Cast<OpenApiSchema>().Distinct().ToList()
+                        .ToDictionary<OpenApiSchema, string>(k => k.Reference.Id);
+
+                    writer.WriteOptionalMap(
+                       OpenApiConstants.Schemas,
+                       Schemas,
+                       (w, key, component) => {
+                           component.SerializeAsV3WithoutReference(w);
+                           });
+                }
                 writer.WriteEndObject();
                 return;  
             }

src/Microsoft.OpenApi/Models/OpenApiDocument.cs

@@ -126,27 +126,50 @@ public void SerializeAsV2(IOpenApiWriter writer)
             // paths
             writer.WriteRequiredObject(OpenApiConstants.Paths, Paths, (w, p) => p.SerializeAsV2(w));
 
-            // Serialize each referenceable object as full object without reference if the reference in the object points to itself. 
-            // If the reference exists but points to other objects, the object is serialized to just that reference.
-
-            // definitions
-            writer.WriteOptionalMap(
-                OpenApiConstants.Definitions,
-                Components?.Schemas,
-                (w, key, component) =>
+            // If references have been inlined we don't need the to render the components section
+            // however if they have cycles, then we will need a component rendered
+            if (writer.GetSettings().ReferenceInline != ReferenceInlineSetting.DoNotInlineReferences)
+            {
+                var loops = writer.GetSettings().LoopDetector.Loops;
+                writer.WriteStartObject();
+                if (loops.TryGetValue(typeof(OpenApiSchema), out List<object> schemas))
                 {
-                    if (component.Reference != null &&
-                        component.Reference.Type == ReferenceType.Schema &&
-                        component.Reference.Id == key)
-                    {
-                        component.SerializeAsV2WithoutReference(w);
-                    }
-                    else
+                    var openApiSchemas = schemas.Cast<OpenApiSchema>().Distinct().ToList()
+                        .ToDictionary<OpenApiSchema, string>(k => k.Reference.Id);
+
+                    writer.WriteOptionalMap(
+                       OpenApiConstants.Definitions,
+                       openApiSchemas,
+                       (w, key, component) =>
+                       {
+                           component.SerializeAsV2WithoutReference(w);
+                       });
+                }
+                writer.WriteEndObject();
+                return;
+            }
+            else
+            {
+                // Serialize each referenceable object as full object without reference if the reference in the object points to itself. 
+                // If the reference exists but points to other objects, the object is serialized to just that reference.
+                // definitions
+                writer.WriteOptionalMap(
+                    OpenApiConstants.Definitions,
+                    Components?.Schemas,
+                    (w, key, component) =>
                     {
-                        component.SerializeAsV2(w);
-                    }
-                });
-
+                        if (component.Reference != null &&
+                            component.Reference.Type == ReferenceType.Schema &&
+                            component.Reference.Id == key)
+                        {
+                            component.SerializeAsV2WithoutReference(w);
+                        }
+                        else
+                        {
+                            component.SerializeAsV2(w);
+                        }
+                    });
+            }
             // parameters
             writer.WriteOptionalMap(
                 OpenApiConstants.Parameters,

src/Microsoft.OpenApi/Models/OpenApiSchema.cs

@@ -251,13 +251,31 @@ public void SerializeAsV3(IOpenApiWriter writer)
                 throw Error.ArgumentNull(nameof(writer));
             }
 
-            if (Reference != null && writer.GetSettings().ReferenceInline != ReferenceInlineSetting.InlineLocalReferences)
+            var settings = writer.GetSettings();
+
+            if (Reference != null)
             {
-                Reference.SerializeAsV3(writer);
-                return;
+                if (settings.ReferenceInline != ReferenceInlineSetting.InlineLocalReferences)
+                {
+                    Reference.SerializeAsV3(writer);
+                    return;
+                }
+
+                // If Loop is detected then just Serialize as a reference.
+                if (!settings.LoopDetector.PushLoop<OpenApiSchema>(this))
+                {
+                    settings.LoopDetector.SaveLoop(this);
+                    Reference.SerializeAsV3(writer);
+                    return;
+                }
             }
 
             SerializeAsV3WithoutReference(writer);
+
+            if (Reference != null)
+            {
+                settings.LoopDetector.PopLoop<OpenApiSchema>();
+            }
         }
 
         /// <summary>

src/Microsoft.OpenApi/Services/LoopDetector.cs

@@ -0,0 +1,74 @@
+using System;
+using System.Collections.Generic;
+using System.Linq;
+using System.Text;
+using System.Threading.Tasks;
+
+namespace Microsoft.OpenApi.Services
+{
+    internal class LoopDetector
+    {
+        private readonly Dictionary<Type, Stack<object>> _loopStacks = new Dictionary<Type, Stack<object>>();
+
+        /// <summary>
+        /// Maintain history of traversals to avoid stack overflows from cycles
+        /// </summary>
+        /// <param name="loopId">Any unique identifier for a stack.</param>
+        /// <param name="key">Identifier used for current context.</param>
+        /// <returns>If method returns false a loop was detected and the key is not added.</returns>
+        public bool PushLoop<T>(T key)
+        {
+            Stack<object> stack;
+            if (!_loopStacks.TryGetValue(typeof(T), out stack))
+            {
+                stack = new Stack<object>();
+                _loopStacks.Add(typeof(T), stack);
+            }
+
+            if (!stack.Contains(key))
+            {
+                stack.Push(key);
+                return true;
+            }
+            else
+            {
+                return false;  // Loop detected
+            }
+        }
+
+        /// <summary>
+        /// Exit from the context in cycle detection
+        /// </summary>
+        /// <param name="loopid">Identifier of loop</param>
+        public void PopLoop<T>()
+        {
+            if (_loopStacks[typeof(T)].Count > 0)
+            {
+                _loopStacks[typeof(T)].Pop();
+            }
+        }
+
+        public void SaveLoop<T>(T loop)
+        {
+            if (!Loops.ContainsKey(typeof(T)))
+            {
+                Loops[typeof(T)] = new List<object>();
+            }
+            Loops[typeof(T)].Add(loop);
+        }
+
+        /// <summary>
+        /// List of Loops detected
+        /// </summary>
+        public Dictionary<Type, List<object>> Loops { get; } = new Dictionary<Type, List<object>>();
+
+        /// <summary>
+        /// Reset loop tracking stack
+        /// </summary>
+        /// <param name="loopid">Identifier of loop to clear</param>
+        internal void ClearLoop<T>()
+        {
+            _loopStacks[typeof(T)].Clear();
+        }
+    }
+}

src/Microsoft.OpenApi/Writers/OpenApiWriterSettings.cs

@@ -1,4 +1,6 @@
 
+using Microsoft.OpenApi.Services;
+
 namespace Microsoft.OpenApi.Writers
 {
     /// <summary>
@@ -25,6 +27,7 @@ public enum ReferenceInlineSetting
     /// </summary>
     public class OpenApiWriterSettings
     {
+        internal LoopDetector LoopDetector { get; } = new LoopDetector();
         /// <summary>
         /// Indicates how references in the source document should be handled.
         /// </summary>