feat: Add writer settings to enable collection sorting using a comparer

src/Microsoft.OpenApi.Hidi/Extensions/OpenApiExtensibleExtensions.cs

@@ -13,7 +13,7 @@ internal static class OpenApiExtensibleExtensions
         /// <param name="extensions">A dictionary of <see cref="IOpenApiExtension"/>.</param>
         /// <param name="extensionKey">The key corresponding to the <see cref="IOpenApiExtension"/>.</param>
         /// <returns>A <see cref="string"/> value matching the provided extensionKey. Return null when extensionKey is not found. </returns>
-        internal static string GetExtension(this Dictionary<string, IOpenApiExtension> extensions, string extensionKey)
+        internal static string GetExtension(this IDictionary<string, IOpenApiExtension> extensions, string extensionKey)
         {
             if (extensions.TryGetValue(extensionKey, out var value) && value is JsonNodeExtension { Node: JsonValue castValue } && castValue.TryGetValue<string>(out var stringValue))
             {

src/Microsoft.OpenApi.Hidi/StatsVisitor.cs

@@ -27,7 +27,7 @@ public override void Visit(IOpenApiSchema schema)
 
         public int HeaderCount { get; set; }
 
-        public override void Visit(Dictionary<string, IOpenApiHeader> headers)
+        public override void Visit(IDictionary<string, IOpenApiHeader> headers)
         {
             HeaderCount++;
         }

src/Microsoft.OpenApi.Workbench/StatsVisitor.cs

@@ -27,7 +27,7 @@ public override void Visit(IOpenApiSchema schema)
 
         public int HeaderCount { get; set; }
 
-        public override void Visit(Dictionary<string, IOpenApiHeader> headers)
+        public override void Visit(IDictionary<string, IOpenApiHeader> headers)
         {
             HeaderCount++;
         }

src/Microsoft.OpenApi/Extensions/DictionaryExtensions.cs

@@ -0,0 +1,51 @@
+using System;
+using System.Collections.Generic;
+using System.Linq;
+
+namespace Microsoft.OpenApi.Extensions
+{
+    /// <summary>
+    /// Dictionary extension methods
+    /// </summary>
+    public static class DictionaryExtensions
+    {
+        /// <summary>
+        /// Returns a new dictionary with entries sorted by key using the default comparer.
+        /// </summary>
+        public static IDictionary<TKey, TValue> Sort<TKey, TValue>(
+            this IDictionary<TKey, TValue> source)
+            where TKey : notnull
+        {
+#if NET7_0_OR_GREATER
+            ArgumentNullException.ThrowIfNull(nameof(source));
+#else
+            if (source == null)
+                throw new ArgumentNullException(nameof(source));
+#endif
+
+            return source.OrderBy(kvp => kvp.Key)
+                               .ToDictionary(kvp => kvp.Key, kvp => kvp.Value);
+        }
+
+        /// <summary>
+        /// Returns a new dictionary with entries sorted by key using a custom comparer.
+        /// </summary>
+        public static IDictionary<TKey, TValue> Sort<TKey, TValue>(
+            this IDictionary<TKey, TValue> source,
+            IComparer<TKey> comparer)
+            where TKey : notnull
+        {
+#if NET7_0_OR_GREATER
+            ArgumentNullException.ThrowIfNull(nameof(source));
+            ArgumentNullException.ThrowIfNull(nameof(comparer));
+#else
+            if (source == null)
+                throw new ArgumentNullException(nameof(source));
+            if (comparer == null)
+                throw new ArgumentNullException(nameof(comparer));
+#endif
+            return source.OrderBy(kvp => kvp.Key, comparer)
+                               .ToDictionary(kvp => kvp.Key, kvp => kvp.Value);
+        }
+    }
+}

src/Microsoft.OpenApi/Extensions/OpenApiExtensibleExtensions.cs

@@ -33,7 +33,7 @@ public static void AddExtension<T>(this T element, string name, IOpenApiExtensio
                 throw new OpenApiException(string.Format(SRResource.ExtensionFieldNameMustBeginWithXDash, name));
             }
 
-            element.Extensions ??= [];
+            element.Extensions ??= new Dictionary<string, IOpenApiExtension>();
             element.Extensions[name] = Utils.CheckArgumentNull(any);
         }
     }

src/Microsoft.OpenApi/Interfaces/IMetadataContainer.cs

@@ -14,5 +14,5 @@ public interface IMetadataContainer
     /// A collection of properties associated with the current OpenAPI element to be used by the application.
     /// Metadata are NOT (de)serialized with the schema and can be used for custom properties.
     /// </summary>
-    Dictionary<string, object>? Metadata { get; set; }
+    IDictionary<string, object>? Metadata { get; set; }
 }

src/Microsoft.OpenApi/Interfaces/IOpenApiExtensible.cs

@@ -13,6 +13,6 @@ public interface IOpenApiExtensible : IOpenApiElement
         /// <summary>
         /// Specification extensions.
         /// </summary>
-        Dictionary<string, IOpenApiExtension>? Extensions { get; set; }
+        IDictionary<string, IOpenApiExtension>? Extensions { get; set; }
     }
 }

src/Microsoft.OpenApi/Interfaces/IOpenApiReadOnlyExtensible.cs

@@ -10,6 +10,6 @@ public interface IOpenApiReadOnlyExtensible
     /// <summary>
     /// Specification extensions.
     /// </summary>
-    Dictionary<string, IOpenApiExtension>? Extensions { get; }
+    IDictionary<string, IOpenApiExtension>? Extensions { get; }
 
 }

src/Microsoft.OpenApi/Models/Interfaces/IOpenApiHeader.cs

@@ -55,11 +55,11 @@ public interface IOpenApiHeader : IOpenApiDescribedElement, IOpenApiReadOnlyExte
     /// <summary>
     /// Examples of the media type.
     /// </summary>
-    public Dictionary<string, IOpenApiExample>? Examples { get; }
+    public IDictionary<string, IOpenApiExample>? Examples { get; }
 
     /// <summary>
     /// A map containing the representations for the header.
     /// </summary>
-    public Dictionary<string, OpenApiMediaType>? Content { get; }
+    public IDictionary<string, OpenApiMediaType>? Content { get; }
 
 }

src/Microsoft.OpenApi/Models/Interfaces/IOpenApiLink.cs

@@ -24,7 +24,7 @@ public interface IOpenApiLink : IOpenApiDescribedElement, IOpenApiReadOnlyExtens
     /// <summary>
     /// A map representing parameters to pass to an operation as specified with operationId or identified via operationRef.
     /// </summary>
-    public Dictionary<string, RuntimeExpressionAnyWrapper>? Parameters { get; }
+    public IDictionary<string, RuntimeExpressionAnyWrapper>? Parameters { get; }
 
     /// <summary>
     /// A literal value or {expression} to use as a request body when calling the target operation.

src/Microsoft.OpenApi/Models/Interfaces/IOpenApiParameter.cs

@@ -81,7 +81,7 @@ public interface IOpenApiParameter : IOpenApiDescribedElement, IOpenApiReadOnlyE
     /// Furthermore, if referencing a schema which contains an example,
     /// the examples value SHALL override the example provided by the schema.
     /// </summary>
-    public Dictionary<string, IOpenApiExample>? Examples { get; }
+    public IDictionary<string, IOpenApiExample>? Examples { get; }
 
     /// <summary>
     /// Example of the media type. The example SHOULD match the specified schema and encoding properties
@@ -102,5 +102,5 @@ public interface IOpenApiParameter : IOpenApiDescribedElement, IOpenApiReadOnlyE
     /// When example or examples are provided in conjunction with the schema object,
     /// the example MUST follow the prescribed serialization strategy for the parameter.
     /// </summary>
-    public Dictionary<string, OpenApiMediaType>? Content { get; }    
+    public IDictionary<string, OpenApiMediaType>? Content { get; }    
 }

src/Microsoft.OpenApi/Models/Interfaces/IOpenApiRequestBody.cs

@@ -19,7 +19,7 @@ public interface IOpenApiRequestBody : IOpenApiDescribedElement, IOpenApiReadOnl
     /// REQUIRED. The content of the request body. The key is a media type or media type range and the value describes it.
     /// For requests that match multiple keys, only the most specific key is applicable. e.g. text/plain overrides text/*
     /// </summary>
-    public Dictionary<string, OpenApiMediaType>? Content { get; }
+    public IDictionary<string, OpenApiMediaType>? Content { get; }
     /// <summary>
     /// Converts the request body to a body parameter in preparation for a v2 serialization.
     /// </summary>

src/Microsoft.OpenApi/Models/Interfaces/IOpenApiResponse.cs

@@ -12,18 +12,18 @@ public interface IOpenApiResponse : IOpenApiDescribedElement, IOpenApiReadOnlyEx
     /// <summary>
     /// Maps a header name to its definition.
     /// </summary>
-    public Dictionary<string, IOpenApiHeader>? Headers { get; }
+    public IDictionary<string, IOpenApiHeader>? Headers { get; }
 
     /// <summary>
     /// A map containing descriptions of potential response payloads.
     /// The key is a media type or media type range and the value describes it.
     /// </summary>
-    public Dictionary<string, OpenApiMediaType>? Content { get; }
+    public IDictionary<string, OpenApiMediaType>? Content { get; }
 
     /// <summary>
     /// A map of operations links that can be followed from the response.
     /// The key of the map is a short name for the link,
     /// following the naming constraints of the names for Component Objects.
     /// </summary>
-    public Dictionary<string, IOpenApiLink>? Links { get; }
+    public IDictionary<string, IOpenApiLink>? Links { get; }
 }

src/Microsoft.OpenApi/Models/Interfaces/IOpenApiSchema.cs

@@ -36,7 +36,7 @@ public interface IOpenApiSchema : IOpenApiDescribedElement, IOpenApiReadOnlyExte
     /// <summary>
     /// $vocabulary- used in meta-schemas to identify the vocabularies available for use in schemas described by that meta-schema.
     /// </summary>
-    public Dictionary<string, bool>? Vocabulary { get; }
+    public IDictionary<string, bool>? Vocabulary { get; }
 
     /// <summary>
     /// $dynamicRef - an applicator that allows for deferring the full resolution until runtime, at which point it is resolved each time it is encountered while evaluating an instance
@@ -52,7 +52,7 @@ public interface IOpenApiSchema : IOpenApiDescribedElement, IOpenApiReadOnlyExte
     /// $defs - reserves a location for schema authors to inline re-usable JSON Schemas into a more general schema. 
     /// The keyword does not directly affect the validation result
     /// </summary>
-    public Dictionary<string, IOpenApiSchema>? Definitions { get; }
+    public IDictionary<string, IOpenApiSchema>? Definitions { get; }
 
     /// <summary>
     /// Follow JSON Schema definition: https://json-schema.org/draft/2020-12/json-schema-validation
@@ -196,7 +196,7 @@ public interface IOpenApiSchema : IOpenApiDescribedElement, IOpenApiReadOnlyExte
     /// Follow JSON Schema definition: https://json-schema.org/draft/2020-12/json-schema-validation
     /// Property definitions MUST be a Schema Object and not a standard JSON Schema (inline or referenced).
     /// </summary>
-    public Dictionary<string, IOpenApiSchema>? Properties { get; }
+    public IDictionary<string, IOpenApiSchema>? Properties { get; }
 
     /// <summary>
     /// Follow JSON Schema definition: https://json-schema.org/draft/2020-12/json-schema-validation
@@ -205,7 +205,7 @@ public interface IOpenApiSchema : IOpenApiDescribedElement, IOpenApiReadOnlyExte
     /// egular expression dialect. Each property value of this object MUST be an object, and each object MUST 
     /// be a valid Schema Object not a standard JSON Schema.
     /// </summary>
-    public Dictionary<string, IOpenApiSchema>? PatternProperties { get; }
+    public IDictionary<string, IOpenApiSchema>? PatternProperties { get; }
 
     /// <summary>
     /// Follow JSON Schema definition: https://json-schema.org/draft/2020-12/json-schema-validation
@@ -279,10 +279,10 @@ public interface IOpenApiSchema : IOpenApiDescribedElement, IOpenApiReadOnlyExte
     /// <summary>
     /// This object stores any unrecognized keywords found in the schema.
     /// </summary>
-    public Dictionary<string, JsonNode>? UnrecognizedKeywords { get; }
+    public IDictionary<string, JsonNode>? UnrecognizedKeywords { get; }
 
     /// <summary>
     /// Follow JSON Schema definition:https://json-schema.org/draft/2020-12/json-schema-validation#section-6.5.4
     /// </summary>
-    public Dictionary<string, HashSet<string>>? DependentRequired { get; }
+    public IDictionary<string, HashSet<string>>? DependentRequired { get; }
 }

src/Microsoft.OpenApi/Models/OpenApiCallback.cs

@@ -22,7 +22,7 @@ public class OpenApiCallback : IOpenApiExtensible, IOpenApiCallback
         /// <summary>
         /// This object MAY be extended with Specification Extensions.
         /// </summary>
-        public Dictionary<string, IOpenApiExtension>? Extensions { get; set; }
+        public IDictionary<string, IOpenApiExtension>? Extensions { get; set; }
 
         /// <summary>
         /// Parameter-less constructor

src/Microsoft.OpenApi/Models/OpenApiComponents.cs

@@ -19,57 +19,57 @@ public class OpenApiComponents : IOpenApiSerializable, IOpenApiExtensible
         /// <summary>
         /// An object to hold reusable <see cref="IOpenApiSchema"/> Objects.
         /// </summary>
-        public Dictionary<string, IOpenApiSchema>? Schemas { get; set; }
+        public IDictionary<string, IOpenApiSchema>? Schemas { get; set; }
 
         /// <summary>
         /// An object to hold reusable <see cref="IOpenApiResponse"/> Objects.
         /// </summary>
-        public Dictionary<string, IOpenApiResponse>? Responses { get; set; }
+        public IDictionary<string, IOpenApiResponse>? Responses { get; set; }
 
         /// <summary>
         /// An object to hold reusable <see cref="IOpenApiParameter"/> Objects.
         /// </summary>
-        public Dictionary<string, IOpenApiParameter>? Parameters { get; set; }
+        public IDictionary<string, IOpenApiParameter>? Parameters { get; set; }
 
         /// <summary>
         /// An object to hold reusable <see cref="OpenApiExample"/> Objects.
         /// </summary>
-        public Dictionary<string, IOpenApiExample>? Examples { get; set; }
+        public IDictionary<string, IOpenApiExample>? Examples { get; set; }
 
         /// <summary>
         /// An object to hold reusable <see cref="IOpenApiRequestBody"/> Objects.
         /// </summary>
-        public Dictionary<string, IOpenApiRequestBody>? RequestBodies { get; set; }
+        public IDictionary<string, IOpenApiRequestBody>? RequestBodies { get; set; }
 
         /// <summary>
         /// An object to hold reusable <see cref="IOpenApiHeader"/> Objects.
         /// </summary>
-        public Dictionary<string, IOpenApiHeader>? Headers { get; set; }
+        public IDictionary<string, IOpenApiHeader>? Headers { get; set; }
 
         /// <summary>
         /// An object to hold reusable <see cref="IOpenApiSecurityScheme"/> Objects.
         /// </summary>
-        public Dictionary<string, IOpenApiSecurityScheme>? SecuritySchemes { get; set; }
+        public IDictionary<string, IOpenApiSecurityScheme>? SecuritySchemes { get; set; }
 
         /// <summary>
         /// An object to hold reusable <see cref="IOpenApiLink"/> Objects.
         /// </summary>
-        public Dictionary<string, IOpenApiLink>? Links { get; set; }
+        public IDictionary<string, IOpenApiLink>? Links { get; set; }
 
         /// <summary>
         /// An object to hold reusable <see cref="OpenApiCallback"/> Objects.
         /// </summary>
-        public Dictionary<string, IOpenApiCallback>? Callbacks { get; set; }
+        public IDictionary<string, IOpenApiCallback>? Callbacks { get; set; }
 
         /// <summary>
         /// An object to hold reusable <see cref="IOpenApiPathItem"/> Object.
         /// </summary>
-        public Dictionary<string, IOpenApiPathItem>? PathItems { get; set; }
+        public IDictionary<string, IOpenApiPathItem>? PathItems { get; set; }
 
         /// <summary>
         /// This object MAY be extended with Specification Extensions.
         /// </summary>
-        public Dictionary<string, IOpenApiExtension>? Extensions { get; set; }
+        public IDictionary<string, IOpenApiExtension>? Extensions { get; set; }
 
         /// <summary>
         /// Parameter-less constructor

src/Microsoft.OpenApi/Models/OpenApiContact.cs

@@ -32,7 +32,7 @@ public class OpenApiContact : IOpenApiSerializable, IOpenApiExtensible
         /// <summary>
         /// This object MAY be extended with Specification Extensions.
         /// </summary>
-        public Dictionary<string, IOpenApiExtension>? Extensions { get; set; }
+        public IDictionary<string, IOpenApiExtension>? Extensions { get; set; }
 
         /// <summary>
         /// Parameter-less constructor

src/Microsoft.OpenApi/Models/OpenApiDiscriminator.cs

@@ -21,12 +21,12 @@ public class OpenApiDiscriminator : IOpenApiSerializable, IOpenApiExtensible
         /// <summary>
         /// An object to hold mappings between payload values and schema names or references.
         /// </summary>
-        public Dictionary<string, OpenApiSchemaReference>? Mapping { get; set; }
+        public IDictionary<string, OpenApiSchemaReference>? Mapping { get; set; }
 
         /// <summary>
         /// This object MAY be extended with Specification Extensions.
         /// </summary>
-        public Dictionary<string, IOpenApiExtension>? Extensions { get; set; }
+        public IDictionary<string, IOpenApiExtension>? Extensions { get; set; }
 
         /// <summary>
         /// Parameter-less constructor