OpenApiDocuments Diff Preview (#303)

 - Updated model to store OpenApiDifference
- Added various OpenApiComparer's to compare fragments of OpenApiDocument

Author: Shwetap05

src/Microsoft.OpenApi/Services/ComparisonContext.cs

@@ -0,0 +1,78 @@
+// Copyright (c) Microsoft Corporation. All rights reserved.
+// Licensed under the MIT license.
+
+using System.Collections.Generic;
+using System.Linq;
+
+namespace Microsoft.OpenApi.Services
+{
+    /// <summary>
+    /// A class encapsulating the comparision context.
+    /// </summary>
+    public class ComparisonContext
+    {
+        private readonly IList<OpenApiDifference> _openApiDifferences = new List<OpenApiDifference>();
+        private readonly Stack<string> _path = new Stack<string>();
+        internal OpenApiComparerFactory OpenApiComparerFactory;
+
+        /// <summary>
+        /// Creates instance of <see cref="ComparisonContext"/>.
+        /// </summary>
+        /// <param name="openApiComparerFactory"></param>
+        public ComparisonContext(OpenApiComparerFactory openApiComparerFactory)
+        {
+            OpenApiComparerFactory = openApiComparerFactory;
+        }
+
+        /// <summary>
+        /// Gets the list of open api differences.
+        /// </summary>
+        public IEnumerable<OpenApiDifference> OpenApiDifferences => _openApiDifferences;
+
+        /// <summary>
+        /// Pointer to the source of difference in the document.
+        /// </summary>
+        public string PathString => "#/" + string.Join("/", _path.Reverse());
+
+        /// <summary>
+        /// Adds an open api difference.
+        /// </summary>
+        /// <param name="openApiDifference">The open api difference to add.</param>
+        public void AddOpenApiDifference(OpenApiDifference openApiDifference)
+        {
+            if (openApiDifference == null)
+            {
+                throw Error.ArgumentNull(nameof(openApiDifference));
+            }
+
+            _openApiDifferences.Add(openApiDifference);
+        }
+
+        /// <summary>
+        /// Allow Rule to indicate difference occured at a deeper context level.
+        /// </summary>
+        /// <param name="segment">Identifier for the context.</param>
+        public void Enter(string segment)
+        {
+            _path.Push(segment);
+        }
+
+        /// <summary>
+        /// Exit from path context level.  Enter and Exit calls should be matched.
+        /// </summary>
+        public void Exit()
+        {
+            _path.Pop();
+        }
+
+        /// <summary>
+        /// Gets the comparer instance for the requested type.
+        /// </summary>
+        /// <typeparam name="T">Type of requested comparer.</typeparam>
+        /// <returns>Comparer instance to use when comparing requested type.</returns>
+        internal OpenApiComparerBase<T> GetComparer<T>()
+        {
+            return OpenApiComparerFactory.GetComparer<T>();
+        }
+    }
+}

src/Microsoft.OpenApi/Services/OpenApiComparer.cs

@@ -14,10 +14,23 @@ public static class OpenApiComparer
         /// <summary>
         /// Compares two <see cref="OpenApiDocument"/>s and returns a list of differences.
         /// </summary>
-        public static List<OpenApiDifference> Compare(OpenApiDocument source, OpenApiDocument target)
+        public static IEnumerable<OpenApiDifference> Compare(OpenApiDocument source, OpenApiDocument target)
         {
-            var diffs = new List<OpenApiDifference>();
-            return diffs;
+            if (source == null)
+            {
+                throw Error.ArgumentNull(nameof(source));
+            }
+
+            if (target == null)
+            {
+                throw Error.ArgumentNull(nameof(target));
+            }
+
+            var comparisionContext = new ComparisonContext(new OpenApiComparerFactory());
+
+            new OpenApiDocumentComparer().Compare(source, target, comparisionContext);
+
+            return comparisionContext.OpenApiDifferences;
         }
     }
 }

src/Microsoft.OpenApi/Services/OpenApiComparerBase.cs

@@ -0,0 +1,107 @@
+// Copyright (c) Microsoft Corporation. All rights reserved.
+// Licensed under the MIT license.
+
+using System;
+
+namespace Microsoft.OpenApi.Services
+{
+    /// <summary>
+    /// Defines behavior for comparing parts of <see cref="OpenAPiDocument"/> class.
+    /// </summary>
+    /// <typeparam name="T">Type of class to compare.</typeparam>
+    public abstract class OpenApiComparerBase<T>
+    {
+        /// <summary>
+        /// Validates a fragment of <see cref="OpenApiDocument"/>.
+        /// </summary>
+        /// <param name="sourceFragment">The source fragment.</param>
+        /// <param name="targetFragment">The target fragment.</param>
+        /// <param name="comparisonContext">Context under which to compare fragment.</param>
+        public abstract void Compare(T sourceFragment, T targetFragment, ComparisonContext comparisonContext);
+
+        /// <summary>
+        /// Compares two string object.
+        /// </summary>
+        /// <param name="source">The source string.</param>
+        /// <param name="target">The target string.</param>
+        /// <param name="comparisonContext">The context under which to compare the objects.</param>
+        internal void Compare(string source, string target, ComparisonContext comparisonContext)
+        {
+            if (string.IsNullOrWhiteSpace(source) && string.IsNullOrWhiteSpace(target))
+            {
+                return;
+            }
+
+            if (string.Compare(source, target, StringComparison.CurrentCultureIgnoreCase) != 0)
+            {
+                comparisonContext.AddOpenApiDifference(new OpenApiDifference
+                {
+                    OpenApiDifferenceOperation = OpenApiDifferenceOperation.Update,
+                    OpenApiComparedElementType = typeof(string),
+                    SourceValue = source,
+                    TargetValue = target,
+                    Pointer = comparisonContext.PathString
+                });
+            }
+        }
+
+        /// <summary>
+        /// Compares two boolean object.
+        /// </summary>
+        /// <param name="source">The source.</param>
+        /// <param name="target">The target.</param>
+        /// <param name="comparisonContext">The context under which to compare the objects.</param>
+        internal void Compare(bool? source, bool? target, ComparisonContext comparisonContext)
+        {
+            if (source == null && target == null)
+            {
+                return;
+            }
+
+            if (source != target)
+            {
+                comparisonContext.AddOpenApiDifference(new OpenApiDifference
+                {
+                    OpenApiDifferenceOperation = OpenApiDifferenceOperation.Update,
+                    OpenApiComparedElementType = typeof(bool),
+                    SourceValue = source,
+                    TargetValue = target,
+                    Pointer = comparisonContext.PathString
+                });
+            }
+        }
+
+        /// <summary>
+        /// Adds a segment to the context path to enable pointing to the current location in the document.
+        /// </summary>
+        /// <param name="comparisonContext">The context under which to compare the objects.</param>
+        /// <param name="segment">An identifier for the segment.</param>
+        /// <param name="openApiDifference">The open api difference to add.</param>
+        internal void WalkAndAddOpenApiDifference(
+            ComparisonContext comparisonContext,
+            string segment,
+            OpenApiDifference openApiDifference)
+        {
+            comparisonContext.Enter(segment.Replace("/", "~1"));
+            openApiDifference.Pointer = comparisonContext.PathString;
+            comparisonContext.AddOpenApiDifference(openApiDifference);
+            comparisonContext.Exit();
+        }
+
+        /// <summary>
+        /// Adds a segment to the context path to enable pointing to the current location in the document.
+        /// </summary>
+        /// <param name="comparisonContext">The context under which to compare the objects.</param>
+        /// <param name="segment">An identifier for the segment.</param>
+        /// <param name="compare">An action that compares objects within the context.</param>
+        protected virtual void WalkAndCompare(
+            ComparisonContext comparisonContext,
+            string segment,
+            Action compare)
+        {
+            comparisonContext.Enter(segment.Replace("/", "~1"));
+            compare();
+            comparisonContext.Exit();
+        }
+    }
+}

src/Microsoft.OpenApi/Services/OpenApiComparerFactory.cs

@@ -0,0 +1,65 @@
+// Copyright (c) Microsoft Corporation. All rights reserved.
+// Licensed under the MIT license.
+
+using System;
+using System.Collections.Generic;
+using Microsoft.OpenApi.Models;
+
+namespace Microsoft.OpenApi.Services
+{
+    /// <summary>
+    /// Defines behavior for registering specific comparer instances and encapsulates default comparers.
+    /// </summary>
+    public class OpenApiComparerFactory
+    {
+        private static readonly Dictionary<Type, object> TypeToDefaultComparerMap = new Dictionary<Type, object>
+        {
+            {typeof(OpenApiPaths), new OpenApiPathsComparer()},
+            {typeof(OpenApiPathItem), new OpenApiPathItemComparer()},
+            {typeof(OpenApiOperation), new OpenApiOperationComparer()},
+            {typeof(IDictionary<OperationType, OpenApiOperation>), new OpenApiOperationsComparer()},
+            {typeof(IList<OpenApiParameter>), new OpenApiParametersComparer()},
+            {typeof(OpenApiParameter), new OpenApiParameterComparer()}
+        };
+
+        private readonly Dictionary<Type, object> _typeToComparerMap = new Dictionary<Type, object>();
+
+        /// <summary>
+        /// Adds a comparer instance to this registry.
+        /// </summary>
+        /// <typeparam name="T">Type of the comparer instance.</typeparam>
+        /// <param name="comparer">Instance of <see cref="OpenApiComparerBase{T}"/> to register.</param>
+        protected void AddComparer<T>(OpenApiComparerBase<T> comparer)
+        {
+            if (comparer == null)
+            {
+                throw new ArgumentNullException(nameof(comparer));
+            }
+
+            _typeToComparerMap.Add(typeof(T), comparer);
+        }
+
+        /// <summary>
+        /// Gets a registered comparer instance for the requested type.
+        /// </summary>
+        /// <typeparam name="T">Type of the comparer.</typeparam>
+        /// <returns>The comparer instance corresponding to the type requested.</returns>
+        internal OpenApiComparerBase<T> GetComparer<T>()
+        {
+            var requestedComparerType = typeof(T);
+
+            if (_typeToComparerMap.TryGetValue(requestedComparerType, out object comparerInstance))
+            {
+                return (OpenApiComparerBase<T>) comparerInstance;
+            }
+
+            if (!TypeToDefaultComparerMap.TryGetValue(requestedComparerType, out comparerInstance))
+            {
+                throw Error.NotSupported(
+                    $"No comparer is registered for type {requestedComparerType.Name}.");
+            }
+
+            return (OpenApiComparerBase<T>) comparerInstance;
+        }
+    }
+}

src/Microsoft.OpenApi/Services/OpenApiDifference.cs

@@ -1,14 +1,39 @@
 // Copyright (c) Microsoft Corporation. All rights reserved.
 // Licensed under the MIT license. 
 
+using System;
 using Microsoft.OpenApi.Models;
 
 namespace Microsoft.OpenApi.Services
 {
     /// <summary>
-    /// Difference point between two <see cref="OpenApiDocument"/>
+    /// Difference point between two <see cref="OpenApiDocument"/>.
     /// </summary>
     public class OpenApiDifference
     {
+        /// <summary>
+        /// The type of the element for which difference found.
+        /// </summary>
+        public Type OpenApiComparedElementType { get; set; }
+
+        /// <summary>
+        /// The open api difference operation.
+        /// </summary>
+        public OpenApiDifferenceOperation OpenApiDifferenceOperation { get; set; }
+
+        /// <summary>
+        /// Pointer to the location of the difference.
+        /// </summary>
+        public string Pointer { get; set; }
+
+        /// <summary>
+        /// The source value.
+        /// </summary>
+        public object SourceValue { get; set; }
+
+        /// <summary>
+        /// The target value.
+        /// </summary>
+        public object TargetValue { get; set; }
     }
 }

src/Microsoft.OpenApi/Services/OpenApiDifferenceOperation.cs

@@ -0,0 +1,15 @@
+// Copyright (c) Microsoft Corporation. All rights reserved.
+// Licensed under the MIT license. 
+
+namespace Microsoft.OpenApi.Services
+{
+    /// <summary>
+    /// The open api difference operation.
+    /// </summary>
+    public enum OpenApiDifferenceOperation
+    {
+        Add,
+        Remove,
+        Update
+    }
+}

src/Microsoft.OpenApi/Services/OpenApiDocumentComparer.cs

@@ -0,0 +1,38 @@
+// Copyright (c) Microsoft Corporation. All rights reserved.
+// Licensed under the MIT license.
+
+using Microsoft.OpenApi.Models;
+
+namespace Microsoft.OpenApi.Services
+{
+    /// <summary>
+    /// Defines behavior for comparing properties of <see cref="OpenApiDocument"/>.
+    /// </summary>
+    public class OpenApiDocumentComparer : OpenApiComparerBase<OpenApiDocument>
+    {
+        /// <summary>
+        /// Executes comparision against source and target <see cref="OpenApiDocument"/>.
+        /// </summary>
+        /// <param name="sourceDocument">The source.</param>
+        /// <param name="targetDocument">The target</param>
+        /// <param name="comparisonContext">Context under which to compare the source and target.</param>
+        public override void Compare(
+            OpenApiDocument sourceDocument,
+            OpenApiDocument targetDocument,
+            ComparisonContext comparisonContext)
+        {
+            comparisonContext.GetComparer<OpenApiPaths>().Compare(
+                sourceDocument.Paths,
+                targetDocument.Paths,
+                comparisonContext);
+
+            // To Do Compare Info
+            // To Do Compare Servers
+            // To Do Compare Components
+            // To Do Compare Security Requirements
+            // To Do Compare Tags
+            // To Do Compare External Docs
+            // To Do Compare Extensions
+        }
+    }
+}