chore: Merge remote-tracking branch 'origin/main' into feat/enable-NRT

MaggieKimani1 · MaggieKimani1 · commit 7a9b01e74b4f · 2025-03-12T10:56:03.000+03:00
diff --git a/.release-please-manifest.json b/.release-please-manifest.json
@@ -1,3 +1,3 @@
 {
-  ".": "2.0.0-preview.11"
+  ".": "2.0.0-preview.12"
 }
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -1,5 +1,13 @@
 # Changelog
 
+## [2.0.0-preview.12](https://github.com/microsoft/OpenAPI.NET/compare/v2.0.0-preview.11...v2.0.0-preview.12) (2025-03-07)
+
+
+### Bug Fixes
+
+* fixes serialization of openApidocs with operation tags with settings to inline references ([8eecae6](https://github.com/microsoft/OpenAPI.NET/commit/8eecae6183f594c5508fc2c74d395c6030ce8727))
+* fixes serialization of openApidocs with operation tags with settings to inline references. ([f67fe64](https://github.com/microsoft/OpenAPI.NET/commit/f67fe64e669a3f8518d89b007150c3e1bdb69fd1))
+
 ## [2.0.0-preview.11](https://github.com/microsoft/OpenAPI.NET/compare/v2.0.0-preview10...v2.0.0-preview.11) (2025-03-03)
 
 
diff --git a/Directory.Build.props b/Directory.Build.props
@@ -12,7 +12,7 @@
     <PackageProjectUrl>https://github.com/Microsoft/OpenAPI.NET</PackageProjectUrl>
     <Copyright>© Microsoft Corporation. All rights reserved.</Copyright>
     <PackageTags>OpenAPI .NET</PackageTags>
-    <Version>2.0.0-preview.11</Version>
+    <Version>2.0.0-preview.12</Version>
   </PropertyGroup>
   <!-- https://github.com/clairernovotny/DeterministicBuilds#deterministic-builds -->
   <PropertyGroup Condition="'$(TF_BUILD)' == 'true'">
diff --git a/build.sh b/build.sh
@@ -0,0 +1,22 @@
+#!/bin/bash
+
+echo "Building Microsoft.OpenApi"
+
+PROJ="$(dirname "$0")/src/Microsoft.OpenApi/Microsoft.OpenApi.csproj"
+dotnet msbuild "$PROJ" /t:restore /p:Configuration=Release
+dotnet msbuild "$PROJ" /t:build /p:Configuration=Release
+dotnet msbuild "$PROJ" /t:pack "/p:Configuration=Release;PackageOutputPath=$(dirname "$0")/artifacts"
+
+echo "Building Microsoft.OpenApi.Readers"
+
+PROJ="$(dirname "$0")/src/Microsoft.OpenApi.Readers/Microsoft.OpenApi.Readers.csproj"
+dotnet msbuild "$PROJ" /t:restore /p:Configuration=Release
+dotnet msbuild "$PROJ" /t:build /p:Configuration=Release
+dotnet msbuild "$PROJ" /t:pack "/p:Configuration=Release;PackageOutputPath=$(dirname "$0")/artifacts"
+
+echo "Building Microsoft.OpenApi.Hidi"
+
+PROJ="$(dirname "$0")/src/Microsoft.OpenApi.Hidi/Microsoft.OpenApi.Hidi.csproj"
+dotnet msbuild "$PROJ" /t:restore /p:Configuration=Release
+dotnet msbuild "$PROJ" /t:build /p:Configuration=Release
+dotnet msbuild "$PROJ" /t:pack "/p:Configuration=Release;PackageOutputPath=$(dirname "$0")/artifacts"
diff --git a/global.json b/global.json
@@ -0,0 +1,5 @@
+{
+  "sdk": {
+    "version": "8.0.406"
+  }
+}
diff --git a/src/Microsoft.OpenApi.Hidi/Microsoft.OpenApi.Hidi.csproj b/src/Microsoft.OpenApi.Hidi/Microsoft.OpenApi.Hidi.csproj
@@ -39,7 +39,7 @@
     <PackageReference Include="System.CommandLine" Version="2.0.0-beta4.22272.1" />
     <PackageReference Include="Microsoft.OData.Edm" Version="8.2.3" />
     <PackageReference Include="Microsoft.OpenApi.OData" Version="2.0.0-preview9" />
-    <PackageReference Include="Microsoft.OpenApi.ApiManifest" Version="2.0.0-preview1" />
+    <PackageReference Include="Microsoft.OpenApi.ApiManifest" Version="2.0.0-preview2" />
     <PackageReference Include="System.CommandLine.Hosting" Version="0.4.0-alpha.22272.1" />
   </ItemGroup>
 
diff --git a/src/Microsoft.OpenApi.Readers/Microsoft.OpenApi.Readers.csproj b/src/Microsoft.OpenApi.Readers/Microsoft.OpenApi.Readers.csproj
@@ -34,7 +34,7 @@
         </PackageReference>
 
         <PackageReference Include="SharpYaml" Version="2.1.1" />
-        <PackageReference Include="System.Text.Json" Version="[8.0,)" />
+        <PackageReference Include="System.Text.Json" Version="[8.0.5,)" />
         <NuGetAuditSuppress Include="https://github.com/advisories/GHSA-hh2w-p6rv-4g7w" />
         <NuGetAuditSuppress Include="https://github.com/advisories/GHSA-8g4q-xg66-9fp4" />
     </ItemGroup>
diff --git a/src/Microsoft.OpenApi/Interfaces/IMetadataContainer.cs b/src/Microsoft.OpenApi/Interfaces/IMetadataContainer.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.Collections.Generic;
@@ -9,11 +9,11 @@ namespace Microsoft.OpenApi.Interfaces
     /// Represents an Open API element that can be annotated with
     /// non-serializable properties in a property bag. 
     /// </summary>
-    public interface IOpenApiAnnotatable
+    public interface IMetadataContainer
     {
         /// <summary>
         /// A collection of properties associated with the current OpenAPI element.
         /// </summary>
-        IDictionary<string, object>? Annotations { get; set; }
+        IDictionary<string, object> Metadata { get; set; }
     }
 }
diff --git a/src/Microsoft.OpenApi/Microsoft.OpenApi.csproj b/src/Microsoft.OpenApi/Microsoft.OpenApi.csproj
@@ -24,7 +24,7 @@
         <ContinuousIntegrationBuild>true</ContinuousIntegrationBuild>
     </PropertyGroup>
     <ItemGroup>        
-        <PackageReference Include="System.Text.Json" Version="[8.0,)" />
+        <PackageReference Include="System.Text.Json" Version="[8.0.5,)" />
         <NuGetAuditSuppress Include="https://github.com/advisories/GHSA-hh2w-p6rv-4g7w" />
         <NuGetAuditSuppress Include="https://github.com/advisories/GHSA-8g4q-xg66-9fp4" />
     </ItemGroup>
diff --git a/src/Microsoft.OpenApi/Models/OpenApiDocument.cs b/src/Microsoft.OpenApi/Models/OpenApiDocument.cs
@@ -24,7 +24,7 @@ namespace Microsoft.OpenApi.Models
     /// <summary>
     /// Describes an OpenAPI object (OpenAPI document). See: https://spec.openapis.org
     /// </summary>
-    public class OpenApiDocument : IOpenApiSerializable, IOpenApiExtensible, IOpenApiAnnotatable
+    public class OpenApiDocument : IOpenApiSerializable, IOpenApiExtensible, IMetadataContainer
     {
         /// <summary>
         /// Register components in the document to the workspace
@@ -109,7 +109,7 @@ public ISet<OpenApiTag>? Tags
         public IDictionary<string, IOpenApiExtension>? Extensions { get; set; } = new Dictionary<string, IOpenApiExtension>();
 
         /// <inheritdoc />
-        public IDictionary<string, object>? Annotations { get; set; }
+        public IDictionary<string, object>? Metadata { get; set; }
 
         /// <summary>
         /// Implements IBaseDocument
@@ -143,7 +143,7 @@ public OpenApiDocument(OpenApiDocument? document)
             Tags = document?.Tags != null ? new HashSet<OpenApiTag>(document.Tags, OpenApiTagComparer.Instance) : null;
             ExternalDocs = document?.ExternalDocs != null ? new(document.ExternalDocs) : null;
             Extensions = document?.Extensions != null ? new Dictionary<string, IOpenApiExtension>(document.Extensions) : null;
-            Annotations = document?.Annotations != null ? new Dictionary<string, object>(document.Annotations) : null;
+            Metadata = document?.Metadata != null ? new Dictionary<string, object>(document.Metadata) : null;
             BaseUri = document?.BaseUri != null ? document.BaseUri : new(OpenApiConstants.BaseRegistryUri + Guid.NewGuid());
         }
 
diff --git a/src/Microsoft.OpenApi/Models/OpenApiOperation.cs b/src/Microsoft.OpenApi/Models/OpenApiOperation.cs
@@ -16,7 +16,7 @@ namespace Microsoft.OpenApi.Models
     /// <summary>
     /// Operation Object.
     /// </summary>
-    public class OpenApiOperation : IOpenApiSerializable, IOpenApiExtensible, IOpenApiAnnotatable
+    public class OpenApiOperation : IOpenApiSerializable, IOpenApiExtensible, IMetadataContainer
     {
         /// <summary>
         /// Default value for <see cref="Deprecated"/>.
@@ -127,7 +127,7 @@ public ISet<OpenApiTagReference>? Tags
         public IDictionary<string, IOpenApiExtension>? Extensions { get; set; } = new Dictionary<string, IOpenApiExtension>();
 
         /// <inheritdoc />
-        public IDictionary<string, object>? Annotations { get; set; }
+        public IDictionary<string, object>? Metadata { get; set; }
 
         /// <summary>
         /// Parameterless constructor
@@ -153,7 +153,7 @@ public OpenApiOperation(OpenApiOperation operation)
             Security = operation.Security != null ? new List<OpenApiSecurityRequirement>(operation.Security) : null;
             Servers = operation.Servers != null ? new List<OpenApiServer>(operation.Servers) : null;
             Extensions = operation.Extensions != null ? new Dictionary<string, IOpenApiExtension>(operation.Extensions) : null;
-            Annotations = operation.Annotations != null ? new Dictionary<string, object>(operation.Annotations) : null;
+            Metadata = operation.Metadata != null ? new Dictionary<string, object>(operation.Metadata) : null;
         }
 
         /// <summary>
diff --git a/src/Microsoft.OpenApi/Models/OpenApiReference.cs b/src/Microsoft.OpenApi/Models/OpenApiReference.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;
@@ -92,7 +92,8 @@ public string? ReferenceV3
                 {
                     return Id;
                 }
-                if (Id is not null && Id.StartsWith("http", StringComparison.OrdinalIgnoreCase))
+                if (Id.StartsWith("http://", StringComparison.OrdinalIgnoreCase) ||
+                    Id.StartsWith("https://", StringComparison.OrdinalIgnoreCase))
                 {
                     return Id;
                 }
@@ -231,7 +232,8 @@ public void SerializeAsV2(IOpenApiWriter writer)
                     return ExternalResource + "#" + Id;
                 }
 
-                if (Id.StartsWith("http", StringComparison.OrdinalIgnoreCase))
+                if (Id.StartsWith("http://", StringComparison.OrdinalIgnoreCase) ||
+                    Id.StartsWith("https://", StringComparison.OrdinalIgnoreCase))
                 {
                     return Id;
                 }
diff --git a/src/Microsoft.OpenApi/Models/References/BaseOpenApiReferenceHolder.cs b/src/Microsoft.OpenApi/Models/References/BaseOpenApiReferenceHolder.cs
@@ -70,7 +70,8 @@ protected BaseOpenApiReferenceHolder(string referenceId, OpenApiDocument? hostDo
     /// <inheritdoc/>
     public virtual void SerializeAsV3(IOpenApiWriter writer)
     {
-        if (!writer.GetSettings().ShouldInlineReference(Reference))
+        if (!writer.GetSettings().ShouldInlineReference(Reference) 
+            || Reference.Type == ReferenceType.Tag) // tags are held as references need to drop in.
         {
             Reference.SerializeAsV3(writer);
         }
diff --git a/test/Microsoft.OpenApi.Hidi.Tests/Services/OpenApiFilterServiceTests.cs b/test/Microsoft.OpenApi.Hidi.Tests/Services/OpenApiFilterServiceTests.cs
@@ -1,13 +1,16 @@
-﻿// Copyright (c) Microsoft Corporation. All rights reserved.
+// Copyright (c) Microsoft Corporation. All rights reserved.
 // Licensed under the MIT license.
 
+using System.Globalization;
 using Microsoft.Extensions.Logging;
+using Microsoft.OpenApi.Extensions;
 using Microsoft.OpenApi.Models;
 using Microsoft.OpenApi.Models.Interfaces;
 using Microsoft.OpenApi.Models.References;
 using Microsoft.OpenApi.Reader;
 using Microsoft.OpenApi.Services;
 using Microsoft.OpenApi.Tests.UtilityFiles;
+using Microsoft.OpenApi.Writers;
 using Moq;
 using Xunit;
 
@@ -235,12 +238,14 @@ public async Task CopiesOverAllReferencedComponentsToTheSubsetDocumentCorrectly(
             using var stream = File.OpenRead(filePath);
             var settings = new OpenApiReaderSettings();
             settings.AddYamlReader();
-            var readResult = await OpenApiDocument.LoadAsync(stream, "yaml", settings);
-            var doc = readResult.Document;
-            if (doc == null)
-            {
-                throw new InvalidOperationException("Failed to load OpenApiDocument.");
-            }
+            var doc = (await OpenApiDocument.LoadAsync(stream, "yaml", settings)).Document;
+            
+            // validated the tags are read as references
+            var openApiOperationTags = doc.Paths["/items"].Operations[OperationType.Get].Tags?.ToArray();
+            Assert.NotNull(openApiOperationTags);
+            Assert.Single(openApiOperationTags);
+            Assert.True(openApiOperationTags[0].UnresolvedReference);
+            
             var predicate = OpenApiFilterService.CreatePredicate(operationIds: operationIds);
             var subsetOpenApiDocument = OpenApiFilterService.CreateFilteredDocument(doc, predicate);
 
@@ -260,6 +265,26 @@ public async Task CopiesOverAllReferencedComponentsToTheSubsetDocumentCorrectly(
             Assert.Single(targetHeaders);
             Assert.NotNull(targetExamples);
             Assert.Single(targetExamples);
+            // validated the tags of the trimmed document are read as references
+            var trimmedOpenApiOperationTags = subsetOpenApiDocument.Paths["/items"].Operations[OperationType.Get].Tags?.ToArray();
+            Assert.NotNull(trimmedOpenApiOperationTags);
+            Assert.Single(trimmedOpenApiOperationTags);
+            Assert.True(trimmedOpenApiOperationTags[0].UnresolvedReference);
+            
+            // Finally try to write the trimmed document as v3 document
+            var outputStringWriter = new StringWriter(CultureInfo.InvariantCulture);
+            var writer = new OpenApiJsonWriter(outputStringWriter)
+            {
+                Settings = new OpenApiWriterSettings()
+                {
+                    InlineExternalReferences = true,
+                    InlineLocalReferences = true
+                }
+            };
+            subsetOpenApiDocument.SerializeAsV3(writer);
+            await writer.FlushAsync();
+            var result = outputStringWriter.ToString();
+            Assert.NotEmpty(result);
         }
 
         [Theory]
diff --git a/test/Microsoft.OpenApi.Hidi.Tests/UtilityFiles/docWithReusableHeadersAndExamples.yaml b/test/Microsoft.OpenApi.Hidi.Tests/UtilityFiles/docWithReusableHeadersAndExamples.yaml
@@ -7,6 +7,8 @@ servers:
 paths:
   /items:
     get:
+      tags:
+        - list.items
       operationId: getItems
       summary: Get a list of items
       responses:
diff --git a/test/Microsoft.OpenApi.Tests/Models/OpenApiDocumentTests.cs b/test/Microsoft.OpenApi.Tests/Models/OpenApiDocumentTests.cs
@@ -92,7 +92,7 @@ public class OpenApiDocumentTests
             {
                 Version = "1.0.0"
             },
-            Annotations = new Dictionary<string, object> { { "key1", "value" } },
+            Metadata = new Dictionary<string, object> { { "key1", "value" } },
             Components = TopLevelReferencingComponents
         };
 
@@ -102,7 +102,7 @@ public class OpenApiDocumentTests
             {
                 Version = "1.0.0"
             },
-            Annotations = new Dictionary<string, object> { { "key1", "value" } },
+            Metadata = new Dictionary<string, object> { { "key1", "value" } },
             Components = TopLevelSelfReferencingComponentsWithOtherProperties
         };
 
@@ -112,7 +112,7 @@ public class OpenApiDocumentTests
             {
                 Version = "1.0.0"
             },
-            Annotations = new Dictionary<string, object> { { "key1", "value" } },
+            Metadata = new Dictionary<string, object> { { "key1", "value" } },
             Components = TopLevelSelfReferencingComponents
         };
 
@@ -489,7 +489,7 @@ public class OpenApiDocumentTests
                     }
                 }
             },
-            Annotations = new Dictionary<string, object> { { "key1", "value" } },
+            Metadata = new Dictionary<string, object> { { "key1", "value" } },
             Components = AdvancedComponentsWithReference
         };
 
@@ -865,7 +865,7 @@ public class OpenApiDocumentTests
                     }
                 }
             },
-            Annotations = new Dictionary<string, object> { { "key1", "value" } },
+            Metadata = new Dictionary<string, object> { { "key1", "value" } },
             Components = AdvancedComponents
         };
 
@@ -1024,7 +1024,7 @@ public class OpenApiDocumentTests
                     }
                 }
             },
-            Annotations = new Dictionary<string, object> { { "key1", "value" } },
+            Metadata = new Dictionary<string, object> { { "key1", "value" } },
             Components = AdvancedComponents
         };
 
@@ -1324,7 +1324,7 @@ public class OpenApiDocumentTests
                     }
                 }
             },
-            Annotations = new Dictionary<string, object> { { "key1", "value" } },
+            Metadata = new Dictionary<string, object> { { "key1", "value" } },
             Components = AdvancedComponents
         };
 
@@ -1830,7 +1830,7 @@ public void OpenApiDocumentCopyConstructorWithAnnotationsSucceeds()
         {
             var baseDocument = new OpenApiDocument
             {
-                Annotations = new Dictionary<string, object>
+                Metadata = new Dictionary<string, object>
                 {
                     ["key1"] = "value1",
                     ["key2"] = 2
@@ -1839,11 +1839,11 @@ public void OpenApiDocumentCopyConstructorWithAnnotationsSucceeds()
 
             var actualDocument = new OpenApiDocument(baseDocument);
 
-            Assert.Equal(baseDocument.Annotations["key1"], actualDocument.Annotations["key1"]);
+            Assert.Equal(baseDocument.Metadata["key1"], actualDocument.Metadata["key1"]);
 
-            baseDocument.Annotations["key1"] = "value2";
+            baseDocument.Metadata["key1"] = "value2";
 
-            Assert.NotEqual(baseDocument.Annotations["key1"], actualDocument.Annotations["key1"]);
+            Assert.NotEqual(baseDocument.Metadata["key1"], actualDocument.Metadata["key1"]);
         }
 
         [Fact]
diff --git a/test/Microsoft.OpenApi.Tests/Models/OpenApiOperationTests.cs b/test/Microsoft.OpenApi.Tests/Models/OpenApiOperationTests.cs
@@ -84,7 +84,7 @@ public class OpenApiOperationTests
                     Description = "serverDescription"
                 }
             },
-            Annotations = new Dictionary<string, object> { { "key1", "value1" }, { "key2", 2 } },
+            Metadata = new Dictionary<string, object> { { "key1", "value1" }, { "key2", 2 } },
         };
 
         private static OpenApiOperation _advancedOperationWithTagsAndSecurity => new()
@@ -844,7 +844,7 @@ public void OpenApiOperationCopyConstructorWithAnnotationsSucceeds()
         {
             var baseOperation = new OpenApiOperation
             {
-                Annotations = new Dictionary<string, object>
+                Metadata = new Dictionary<string, object>
                 {
                     ["key1"] = "value1",
                     ["key2"] = 2
@@ -853,11 +853,11 @@ public void OpenApiOperationCopyConstructorWithAnnotationsSucceeds()
 
             var actualOperation = new OpenApiOperation(baseOperation);
 
-            Assert.Equal(baseOperation.Annotations["key1"], actualOperation.Annotations["key1"]);
+            Assert.Equal(baseOperation.Metadata["key1"], actualOperation.Metadata["key1"]);
 
-            baseOperation.Annotations["key1"] = "value2";
+            baseOperation.Metadata["key1"] = "value2";
 
-            Assert.NotEqual(baseOperation.Annotations["key1"], actualOperation.Annotations["key1"]);
+            Assert.NotEqual(baseOperation.Metadata["key1"], actualOperation.Metadata["key1"]);
         }
     }
 }
diff --git a/test/Microsoft.OpenApi.Tests/Models/OpenApiReferenceTests.cs b/test/Microsoft.OpenApi.Tests/Models/OpenApiReferenceTests.cs
diff --git a/test/Microsoft.OpenApi.Tests/Models/References/OpenApiTagReferenceTest.cs b/test/Microsoft.OpenApi.Tests/Models/References/OpenApiTagReferenceTest.cs
diff --git a/test/Microsoft.OpenApi.Tests/PublicApi/PublicApi.approved.txt b/test/Microsoft.OpenApi.Tests/PublicApi/PublicApi.approved.txt

Original file line number	Diff line number	Diff line change
`@@ -1,3 +1,3 @@`
`1`	`1`	`{`
`2`		`- ".": "2.0.0-preview.11"`
	`2`	`+ ".": "2.0.0-preview.12"`
`3`	`3`	`}`
-Original file line number
+Diff line change
@@ @@ -0,0 +1,5 @@ @@
 +{
 +  "sdk": {
 +    "version": "8.0.406"
 +  }
 +}
Original file line number	Diff line number	Diff line change
`@@ -1,4 +1,4 @@`
`1`		`-// Copyright (c) Microsoft Corporation. All rights reserved.`
	`1`	`+// Copyright (c) Microsoft Corporation. All rights reserved.`
`2`	`2`	`// Licensed under the MIT license.`
`3`	`3`
`4`	`4`	`using System.Collections.Generic;`
`@@ -9,11 +9,11 @@ namespace Microsoft.OpenApi.Interfaces`
`9`	`9`	`/// Represents an Open API element that can be annotated with`
`10`	`10`	`/// non-serializable properties in a property bag.`
`11`	`11`	`/// </summary>`
`12`		`- public interface IOpenApiAnnotatable`
	`12`	`+ public interface IMetadataContainer`
`13`	`13`	`{`
`14`	`14`	`/// <summary>`
`15`	`15`	`/// A collection of properties associated with the current OpenAPI element.`
`16`	`16`	`/// </summary>`
`17`		`- IDictionary<string, object>? Annotations { get; set; }`
	`17`	`+ IDictionary<string, object> Metadata { get; set; }`
`18`	`18`	`}`
`19`	`19`	`}`