Merge pull request #19 from BinkyLabs/feat/enum-version

adds new OAS vesion and serialization/deserialization infrastructure

Author: baywet

src/Microsoft.OpenApi.Hidi/OpenApiService.cs

@@ -67,9 +67,9 @@ public static async Task TransformOpenApiDocumentAsync(HidiOptions options, ILog
                     throw new IOException($"The file {options.Output} already exists. Please input a new file path.");
                 }
 
-                // Default to yaml and OpenApiVersion 3_1 during csdl to OpenApi conversion
+                // Default to yaml and OpenApiVersion 3_2 during csdl to OpenApi conversion
                 var openApiFormat = options.OpenApiFormat ?? (!string.IsNullOrEmpty(options.OpenApi) ? GetOpenApiFormat(options.OpenApi, logger) : OpenApiConstants.Yaml);
-                var openApiVersion = options.Version != null ? TryParseOpenApiSpecVersion(options.Version) : OpenApiSpecVersion.OpenApi3_1;
+                var openApiVersion = options.Version != null ? TryParseOpenApiSpecVersion(options.Version) : OpenApiSpecVersion.OpenApi3_2;
 
                 // If ApiManifest is provided, set the referenced OpenAPI document
                 var apiDependency = await FindApiDependencyAsync(options.FilterOptions.FilterByApiManifest, logger, cancellationToken).ConfigureAwait(false);

src/Microsoft.OpenApi.Hidi/OpenApiSpecVersionHelper.cs

@@ -35,8 +35,12 @@ public static OpenApiSpecVersion TryParseOpenApiSpecVersion(string value)
             {
                 return OpenApiSpecVersion.OpenApi3_1;
             }
+            else if (majorVersion == 3 && minorVersion == 2)
+            {
+                return OpenApiSpecVersion.OpenApi3_2;
+            }
 
-            return OpenApiSpecVersion.OpenApi3_1; // default
+            return OpenApiSpecVersion.OpenApi3_2; // default
         }
     }
 }

src/Microsoft.OpenApi.Workbench/MainModel.cs

@@ -155,6 +155,7 @@ public OpenApiSpecVersion Version
                 OnPropertyChanged(nameof(IsV2_0));
                 OnPropertyChanged(nameof(IsV3_0));
                 OnPropertyChanged(nameof(IsV3_1));
+                OnPropertyChanged(nameof(IsV3_2));
             }
         }
 
@@ -188,6 +189,12 @@ public bool IsV3_1
             set => Version = value ? OpenApiSpecVersion.OpenApi3_1 : Version;
         }
 
+        public bool IsV3_2
+        {
+            get => Version == OpenApiSpecVersion.OpenApi3_2;
+            set => Version = value ? OpenApiSpecVersion.OpenApi3_2 : Version;
+        }
+
         /// <summary>
         /// Handling method when the property with given name has changed.
         /// </summary>

src/Microsoft.OpenApi/Extensions/OpenApiSerializableExtensions.cs

@@ -111,6 +111,10 @@ public static Task SerializeAsync<T>(this T element, IOpenApiWriter writer, Open
 
             switch (specVersion)
             {
+                case OpenApiSpecVersion.OpenApi3_2:
+                    element.SerializeAsV32(writer);
+                    break;
+
                 case OpenApiSpecVersion.OpenApi3_1:
                     element.SerializeAsV31(writer);
                     break;

src/Microsoft.OpenApi/Interfaces/IOpenApiSerializable.cs

@@ -8,6 +8,11 @@ namespace Microsoft.OpenApi
     /// </summary>
     public interface IOpenApiSerializable : IOpenApiElement
     {
+        /// <summary>
+        /// Serialize OpenAPI element into v3.2
+        /// </summary>
+        /// <param name="writer"></param>
+        void SerializeAsV32(IOpenApiWriter writer);
         /// <summary>
         /// Serialize OpenAPI element into v3.1
         /// </summary>

src/Microsoft.OpenApi/Models/BaseOpenApiReference.cs

@@ -150,12 +150,27 @@ public BaseOpenApiReference(BaseOpenApiReference reference)
             HostDocument = reference.HostDocument;
         }
 
+        /// <inheritdoc/>
+        public virtual void SerializeAsV32(IOpenApiWriter writer)
+        {
+            SerializeInternal(writer, SerializeAdditionalV32Properties);
+        }
+
         /// <inheritdoc/>
         public virtual void SerializeAsV31(IOpenApiWriter writer)
         {
             SerializeInternal(writer, SerializeAdditionalV31Properties);
         }
 
+        /// <summary>
+        /// Serialize additional properties for Open Api v3.2.
+        /// </summary>
+        /// <param name="writer"></param>
+        protected virtual void SerializeAdditionalV32Properties(IOpenApiWriter writer)
+        {
+            // noop for the base type
+        }
+
         /// <summary>
         /// Serialize additional properties for Open Api v3.1.
         /// </summary>

src/Microsoft.OpenApi/Models/JsonSchemaReference.cs

@@ -71,11 +71,20 @@ public JsonSchemaReference(JsonSchemaReference reference) : base(reference)
 
     /// <inheritdoc/>
     protected override void SerializeAdditionalV31Properties(IOpenApiWriter writer)
+    {
+        SerializeAdditionalV3XProperties(writer, base.SerializeAdditionalV31Properties);
+    }
+    /// <inheritdoc/>
+    protected override void SerializeAdditionalV32Properties(IOpenApiWriter writer)
+    {
+        SerializeAdditionalV3XProperties(writer, base.SerializeAdditionalV32Properties);
+    }
+    private void SerializeAdditionalV3XProperties(IOpenApiWriter writer, Action<IOpenApiWriter> baseSerializer)
     {
         if (Type != ReferenceType.Schema) throw new InvalidOperationException(
             $"JsonSchemaReference can only be serialized for ReferenceType.Schema, but was {Type}.");
 
-        base.SerializeAdditionalV31Properties(writer);        
+        baseSerializer(writer);
         // Additional schema metadata annotations in 3.1
         writer.WriteOptionalObject(OpenApiConstants.Default, Default, (w, d) => w.WriteAny(d));
         writer.WriteProperty(OpenApiConstants.Title, Title);

src/Microsoft.OpenApi/Models/OpenApiCallback.cs

@@ -50,6 +50,16 @@ public void AddPathItem(RuntimeExpression expression, IOpenApiPathItem pathItem)
             PathItems.Add(expression, pathItem);
         }
 
+        /// <summary>
+        /// Serialize <see cref="OpenApiCallback"/> to Open Api v3.2
+        /// </summary>
+        /// <param name="writer"></param>
+        /// <exception cref="System.NotImplementedException"></exception>
+        public virtual void SerializeAsV32(IOpenApiWriter writer)
+        {
+            SerializeInternal(writer, OpenApiSpecVersion.OpenApi3_2, (writer, element) => element.SerializeAsV32(writer));
+        }
+
         /// <summary>
         /// Serialize <see cref="OpenApiCallback"/> to Open Api v3.1
         /// </summary>

src/Microsoft.OpenApi/Models/OpenApiComponents.cs

@@ -90,19 +90,32 @@ public OpenApiComponents(OpenApiComponents? components)
             Extensions = components?.Extensions != null ? new Dictionary<string, IOpenApiExtension>(components.Extensions) : null;
         }
 
+        /// <summary>
+        /// Serialize <see cref="OpenApiComponents"/> to Open API v3.2.
+        /// </summary>
+        /// <param name="writer"></param>
+        public virtual void SerializeAsV32(IOpenApiWriter writer)
+        {
+            SerializeAsV3X(writer, OpenApiSpecVersion.OpenApi3_2, (writer, element) => element.SerializeAsV32(writer), (writer, referenceElement) => referenceElement.SerializeAsV32(writer));
+        }
+
         /// <summary>
         /// Serialize <see cref="OpenApiComponents"/> to Open API v3.1.
         /// </summary>
         /// <param name="writer"></param>
         public virtual void SerializeAsV31(IOpenApiWriter writer)
+        {
+            SerializeAsV3X(writer, OpenApiSpecVersion.OpenApi3_1, (writer, element) => element.SerializeAsV31(writer), (writer, referenceElement) => referenceElement.SerializeAsV31(writer));
+        }
+        private void SerializeAsV3X(IOpenApiWriter writer, OpenApiSpecVersion version, Action<IOpenApiWriter, IOpenApiSerializable> callback, Action<IOpenApiWriter, IOpenApiReferenceHolder> action)
         {
             Utils.CheckArgumentNull(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().InlineLocalReferences)
             {
-                RenderComponents(writer, (writer, element) => element.SerializeAsV31(writer), OpenApiSpecVersion.OpenApi3_1);                
+                RenderComponents(writer, callback, version);
                 return;
             }
 
@@ -116,16 +129,15 @@ public virtual void SerializeAsV31(IOpenApiWriter writer)
             {
                 if (component is OpenApiPathItemReference reference)
                 {
-                    reference.SerializeAsV31(w);
+                    action(w, reference);
                 }
                 else
                 {
-                    component.SerializeAsV31(w);
+                    callback(w, component);
                 }
             });
 
-            SerializeInternal(writer, OpenApiSpecVersion.OpenApi3_1, (writer, element) => element.SerializeAsV31(writer),
-               (writer, referenceElement) => referenceElement.SerializeAsV31(writer));
+            SerializeInternal(writer, version, callback, action);
         }
 
         /// <summary>

src/Microsoft.OpenApi/Models/OpenApiContact.cs

@@ -47,6 +47,14 @@ public OpenApiContact(OpenApiContact contact)
             Email = contact?.Email ?? Email;
             Extensions = contact?.Extensions != null ? new Dictionary<string, IOpenApiExtension>(contact.Extensions) : null;
         }
+        /// <summary>
+        /// Serialize <see cref="OpenApiContact"/> to Open Api v3.2
+        /// </summary>
+        /// <param name="writer"></param>
+        public virtual void SerializeAsV32(IOpenApiWriter writer)
+        {
+            WriteInternal(writer, OpenApiSpecVersion.OpenApi3_2);
+        }
 
         /// <summary>
         /// Serialize <see cref="OpenApiContact"/> to Open Api v3.1