Merge remote-tracking branch 'origin/release/2.0.0' into mk/sync-v2-with-vnext

Author: MaggieKimani1

src/Microsoft.OpenApi.Hidi/OpenApiService.cs

@@ -1,4 +1,4 @@
-// Copyright (c) Microsoft Corporation. All rights reserved.
+// Copyright (c) Microsoft Corporation. All rights reserved.
 // Licensed under the MIT license.
 
 using System;
@@ -79,7 +79,7 @@ public static async Task TransformOpenApiDocumentAsync(HidiOptions options, ILog
 
                 // Default to yaml and OpenApiVersion 3 during csdl to OpenApi conversion
                 var openApiFormat = options.OpenApiFormat ?? (!string.IsNullOrEmpty(options.OpenApi) ? GetOpenApiFormat(options.OpenApi, logger) : OpenApiFormat.Yaml);
-                var openApiVersion = options.Version != null ? TryParseOpenApiSpecVersion(options.Version) : OpenApiSpecVersion.OpenApi3_0;
+                var openApiVersion = options.Version != null ? TryParseOpenApiSpecVersion(options.Version) : OpenApiSpecVersion.OpenApi3_1;
 
                 // If ApiManifest is provided, set the referenced OpenAPI document
                 var apiDependency = await FindApiDependencyAsync(options.FilterOptions.FilterByApiManifest, logger, cancellationToken).ConfigureAwait(false);
@@ -768,7 +768,7 @@ internal static async Task PluginManifestAsync(HidiOptions options, ILogger logg
             // Write OpenAPI to Output folder
             options.Output = new(Path.Combine(options.OutputFolder, "openapi.json"));
             options.TerseOutput = true;
-            WriteOpenApi(options, OpenApiFormat.Json, OpenApiSpecVersion.OpenApi3_0, document, logger);
+            WriteOpenApi(options, OpenApiFormat.Json, OpenApiSpecVersion.OpenApi3_1, document, logger);
 
             // Create OpenAIPluginManifest from ApiDependency and OpenAPI document
             var manifest = new OpenAIPluginManifest

src/Microsoft.OpenApi.Hidi/OpenApiSpecVersionHelper.cs

@@ -2,7 +2,6 @@
 // Licensed under the MIT license.
 
 using System;
-using System.Linq;
 
 namespace Microsoft.OpenApi.Hidi
 {
@@ -14,17 +13,30 @@ public static OpenApiSpecVersion TryParseOpenApiSpecVersion(string value)
             {
                 throw new InvalidOperationException("Please provide a version");
             }
-            var res = value.Split('.', StringSplitOptions.RemoveEmptyEntries).FirstOrDefault();
+            // Split the version string by the dot
+            var versionSegments = value.Split('.', StringSplitOptions.RemoveEmptyEntries);
 
-            if (int.TryParse(res, out var result))
+            if (!int.TryParse(versionSegments[0], out var majorVersion)
+                || !int.TryParse(versionSegments[1], out var minorVersion))
             {
-                if (result is >= 2 and < 3)
-                {
-                    return OpenApiSpecVersion.OpenApi2_0;
-                }
+                throw new InvalidOperationException("Invalid version format. Please provide a valid OpenAPI version (e.g., 2.0, 3.0, 3.1).");
             }
 
-            return OpenApiSpecVersion.OpenApi3_0; // default
+            // Check for specific version matches
+            if (majorVersion == 2)
+            {
+                return OpenApiSpecVersion.OpenApi2_0;
+            }
+            else if (majorVersion == 3 && minorVersion == 0)
+            {
+                return OpenApiSpecVersion.OpenApi3_0;
+            }
+            else if (majorVersion == 3 && minorVersion == 1)
+            {
+                return OpenApiSpecVersion.OpenApi3_1;
+            }
+
+            return OpenApiSpecVersion.OpenApi3_1; // default
         }
     }
 }

src/Microsoft.OpenApi/Models/OpenApiConstants.cs

@@ -700,6 +700,16 @@ public static class OpenApiConstants
         /// </summary>
         public const string ComponentsSegment = "/components/";
 
+        /// <summary>
+        /// Field: Null
+        /// </summary>
+        public const string Null = "null";
+
+        /// <summary>
+        /// Field: Nullable extension
+        /// </summary>
+        public const string NullableExtension = "x-nullable";
+
         #region V2.0
 
         /// <summary>

src/Microsoft.OpenApi/Models/OpenApiDocument.cs

@@ -24,7 +24,7 @@ namespace Microsoft.OpenApi.Models
     public class OpenApiDocument : IOpenApiSerializable, IOpenApiExtensible, IOpenApiAnnotatable
     {
         /// <summary>
-        /// Related workspace containing OpenApiDocuments that are referenced in this document
+        /// Related workspace containing components that are referenced in a document
         /// </summary>
         public OpenApiWorkspace Workspace { get; set; }
 

src/Microsoft.OpenApi/Models/OpenApiReference.cs

@@ -95,6 +95,10 @@ public string ReferenceV3
                 {
                     return Id;
                 }
+                if (Id.StartsWith("http"))
+                {
+                    return Id;
+                }
 
                 return "#/components/" + Type.Value.GetDisplayName() + "/" + Id;
             }
@@ -228,7 +232,12 @@ private string GetExternalReferenceV3()
                 {
                     return ExternalResource + "#" + Id;
                 }
-                
+
+                if (Id.StartsWith("http"))
+                {
+                    return Id;
+                }
+
                 if (Type.HasValue)
                 {
                     return ExternalResource + "#/components/" + Type.Value.GetDisplayName() + "/"+ Id; 

src/Microsoft.OpenApi/Models/OpenApiSchema.cs

@@ -487,14 +487,7 @@ public void SerializeInternal(IOpenApiWriter writer, OpenApiSpecVersion version,
             writer.WriteOptionalCollection(OpenApiConstants.Enum, Enum, (nodeWriter, s) => nodeWriter.WriteAny(s));
 
             // type
-            if (Type?.GetType() == typeof(string))
-            {
-                writer.WriteProperty(OpenApiConstants.Type, (string)Type);
-            }
-            else
-            {
-                writer.WriteOptionalCollection(OpenApiConstants.Type, (string[])Type, (w, s) => w.WriteRaw(s));
-            }
+            SerializeTypeProperty(Type, writer, version);
 
             // allOf
             writer.WriteOptionalCollection(OpenApiConstants.AllOf, AllOf, (w, s) => s.SerializeAsV3(w));
@@ -537,7 +530,10 @@ public void SerializeInternal(IOpenApiWriter writer, OpenApiSpecVersion version,
             writer.WriteOptionalObject(OpenApiConstants.Default, Default, (w, d) => w.WriteAny(d));
 
             // nullable
-            writer.WriteProperty(OpenApiConstants.Nullable, Nullable, false);
+            if (version is OpenApiSpecVersion.OpenApi3_0)
+            {
+                writer.WriteProperty(OpenApiConstants.Nullable, Nullable, false);
+            }
 
             // discriminator
             writer.WriteOptionalObject(OpenApiConstants.Discriminator, Discriminator, (w, s) => s.SerializeAsV3(w));
@@ -674,7 +670,14 @@ internal void SerializeAsV2(
             writer.WriteStartObject();
 
             // type
-            writer.WriteProperty(OpenApiConstants.Type, (string)Type);
+            if (Type is string[] array)
+            {
+                DowncastTypeArrayToV2OrV3(array, writer, OpenApiSpecVersion.OpenApi2_0);
+            }
+            else 
+            {
+                writer.WriteProperty(OpenApiConstants.Type, (string)Type);
+            }
 
             // description
             writer.WriteProperty(OpenApiConstants.Description, Description);
@@ -803,6 +806,35 @@ internal void SerializeAsV2(
             writer.WriteEndObject();
         }
 
+        private void SerializeTypeProperty(object type, IOpenApiWriter writer, OpenApiSpecVersion version)
+        {
+            if (type?.GetType() == typeof(string))
+            {
+                // check whether nullable is true for upcasting purposes
+                if (Nullable || Extensions.ContainsKey(OpenApiConstants.NullableExtension))
+                {
+                    // create a new array and insert the type and "null" as values
+                    Type = new[] { (string)Type, OpenApiConstants.Null };
+                }
+                else
+                {
+                    writer.WriteProperty(OpenApiConstants.Type, (string)Type);
+                }
+            }
+            if (Type is string[] array)
+            {
+                // type
+                if (version is OpenApiSpecVersion.OpenApi3_0)
+                {
+                    DowncastTypeArrayToV2OrV3(array, writer, OpenApiSpecVersion.OpenApi3_0);
+                }
+                else
+                {
+                    writer.WriteOptionalCollection(OpenApiConstants.Type, (string[])Type, (w, s) => w.WriteRaw(s));
+                }
+            }
+        }
+
         private object DeepCloneType(object type)
         {
             if (type == null)
@@ -826,5 +858,38 @@ private object DeepCloneType(object type)
 
             return null;
         }
+
+        private void DowncastTypeArrayToV2OrV3(string[] array, IOpenApiWriter writer, OpenApiSpecVersion version)
+        {
+            /* If the array has one non-null value, emit Type as string
+            * If the array has one null value, emit x-nullable as true
+            * If the array has two values, one null and one non-null, emit Type as string and x-nullable as true
+            * If the array has more than two values or two non-null values, do not emit type
+            * */
+
+            var nullableProp = version.Equals(OpenApiSpecVersion.OpenApi2_0) 
+                ? OpenApiConstants.NullableExtension
+                : OpenApiConstants.Nullable;
+
+            if (array.Length is 1)
+            {
+                var value = array[0];
+                if (value is OpenApiConstants.Null)
+                {
+                    writer.WriteProperty(nullableProp, true);
+                }
+                else
+                {
+                    writer.WriteProperty(OpenApiConstants.Type, value);
+                }
+            }
+            else if (array.Length is 2 && array.Contains(OpenApiConstants.Null))
+            {
+                // Find the non-null value and write it out
+                var nonNullValue = array.First(v => v != OpenApiConstants.Null);
+                writer.WriteProperty(OpenApiConstants.Type, nonNullValue);
+                writer.WriteProperty(nullableProp, true);
+            }
+        }
     }
 }

src/Microsoft.OpenApi/Models/References/OpenApiSchemaReference.cs

@@ -1,12 +1,10 @@
 // Copyright (c) Microsoft Corporation. All rights reserved.
 // Licensed under the MIT license.
 
-using Microsoft.OpenApi.Any;
 using Microsoft.OpenApi.Interfaces;
 using Microsoft.OpenApi.Writers;
 using System;
 using System.Collections.Generic;
-using System.Runtime;
 using System.Text.Json.Nodes;
 
 namespace Microsoft.OpenApi.Models.References

src/Microsoft.OpenApi/Reader/OpenApiJsonReader.cs

@@ -192,7 +192,8 @@ private JsonNode LoadJsonNodes(TextReader input)
         private async Task<OpenApiDiagnostic> LoadExternalRefs(OpenApiDocument document, CancellationToken cancellationToken, OpenApiReaderSettings settings, string format = null)
         {
             // Create workspace for all documents to live in.
-            var openApiWorkSpace = new OpenApiWorkspace();
+            var baseUrl = settings.BaseUrl ?? new Uri(OpenApiConstants.BaseRegistryUri);
+            var openApiWorkSpace = new OpenApiWorkspace(baseUrl);
 
             // Load this root document into the workspace
             var streamLoader = new DefaultStreamLoader(settings.BaseUrl);

src/Microsoft.OpenApi/Reader/Services/DefaultStreamLoader.cs

@@ -45,7 +45,9 @@ public Stream Load(Uri uri)
         /// <exception cref="ArgumentException"></exception>
         public async Task<Stream> LoadAsync(Uri uri)
         {
-            var absoluteUri = new Uri(baseUrl, uri);
+            Uri absoluteUri;
+            absoluteUri = baseUrl.AbsoluteUri.Equals(OpenApiConstants.BaseRegistryUri) ? new Uri(Directory.GetCurrentDirectory() + uri) 
+                : new Uri(baseUrl, uri);
 
             switch (absoluteUri.Scheme)
             {

src/Microsoft.OpenApi/Reader/Services/OpenApiWorkspaceLoader.cs

@@ -28,7 +28,7 @@ internal async Task<OpenApiDiagnostic> LoadAsync(OpenApiReference reference,
         {
             _workspace.AddDocumentId(reference.ExternalResource, document.BaseUri);
             var version = diagnostic?.SpecificationVersion ?? OpenApiSpecVersion.OpenApi3_0;
-            _workspace.RegisterComponents(document, version);
+            _workspace.RegisterComponents(document);
             document.Workspace = _workspace;
 
             // Collect remote references by walking document