Update to Microsoft.OpenApi v2.0.0-preview5 (#60002)

* Update to Microsoft.OpenApi v2.0.0-preview5

* Address feedback

* Update src/OpenApi/test/Microsoft.AspNetCore.OpenApi.Tests/Services/OpenApiDocumentService/OpenApiDocumentServiceTests.Operations.cs

* Update src/OpenApi/test/Microsoft.AspNetCore.OpenApi.Tests/Services/OpenApiDocumentService/OpenApiDocumentServiceTests.Operations.cs

Co-authored-by: Brennan <[email protected]>

---------

Co-authored-by: Brennan <[email protected]>

eng/Versions.props

@@ -335,8 +335,8 @@
     <XunitExtensibilityExecutionVersion>$(XunitVersion)</XunitExtensibilityExecutionVersion>
     <XUnitRunnerVisualStudioVersion>2.8.2</XUnitRunnerVisualStudioVersion>
     <MicrosoftDataSqlClientVersion>5.2.2</MicrosoftDataSqlClientVersion>
-    <MicrosoftOpenApiVersion>2.0.0-preview4</MicrosoftOpenApiVersion>
-    <MicrosoftOpenApiReadersVersion>2.0.0-preview4</MicrosoftOpenApiReadersVersion>
+    <MicrosoftOpenApiVersion>2.0.0-preview5</MicrosoftOpenApiVersion>
+    <MicrosoftOpenApiReadersVersion>2.0.0-preview5</MicrosoftOpenApiReadersVersion>
     <!-- dotnet tool versions (see also auto-updated DotnetEfVersion property). -->
     <DotnetDumpVersion>6.0.322601</DotnetDumpVersion>
     <DotnetServeVersion>1.10.93</DotnetServeVersion>

eng/testing/linker/project.csproj.template

@@ -16,8 +16,6 @@
     <InterceptorsPreviewNamespaces>$(InterceptorsPreviewNamespaces);Microsoft.AspNetCore.Http.Generated</InterceptorsPreviewNamespaces>
     <!-- Ensure individual warnings are shown when publishing -->
     <TrimmerSingleWarn>false</TrimmerSingleWarn>
-    <!-- But ignore the single warn files marked below to suppress their known warnings. -->
-    <NoWarn>$(NoWarn);IL2104;IL3053</NoWarn>
     {AdditionalProperties}
   </PropertyGroup>
 
@@ -29,19 +27,4 @@
     {AdditionalProjectReferences}
   </ItemGroup>
 
-  <!-- Single warn the following assemblies, which have known warnings, so the warnings can be suppressed for now.
-  Remove this (and the above NoWarn IL2104) once  https://github.com/microsoft/OpenAPI.NET/issues/1875 is addressed. -->
-  <Target Name="ConfigureTrimming"
-          BeforeTargets="PrepareForILLink">
-    <ItemGroup>
-      <IlcArg Include="--singlewarnassembly:Microsoft.OpenApi" />
-    </ItemGroup>
-    <ItemGroup>
-      <ManagedAssemblyToLink Condition="'%(Filename)' == 'Microsoft.OpenApi'">
-        <IsTrimmable>true</IsTrimmable>
-        <TrimmerSingleWarn>true</TrimmerSingleWarn>
-      </ManagedAssemblyToLink>
-    </ItemGroup>
-  </Target>
-
 </Project>

src/OpenApi/src/Extensions/OpenApiDocumentExtensions.cs

@@ -23,7 +23,7 @@ internal static class OpenApiDocumentExtensions
         document.Components.Schemas[schemaId] = schema;
         document.Workspace ??= new();
         var location = document.BaseUri + "/components/schemas/" + schemaId;
-        document.Workspace.RegisterComponent(location, schema);
+        document.Workspace.RegisterComponentForDocument(document, schema, location);
         return new OpenApiSchemaReference(schemaId, document);
     }
 }

src/OpenApi/src/Extensions/OpenApiEndpointRouteBuilderExtensions.cs

@@ -59,12 +59,12 @@ public static class OpenApiEndpointRouteBuilderExtensions
                     {
                         if (UseYaml(pattern))
                         {
-                            document.Serialize(new OpenApiYamlWriter(writer), documentOptions.OpenApiVersion);
+                            await document.SerializeAsync(new OpenApiYamlWriter(writer), documentOptions.OpenApiVersion);
                             context.Response.ContentType = "text/plain+yaml;charset=utf-8";
                         }
                         else
                         {
-                            document.Serialize(new OpenApiJsonWriter(writer), documentOptions.OpenApiVersion);
+                            await document.SerializeAsync(new OpenApiJsonWriter(writer), documentOptions.OpenApiVersion);
                             context.Response.ContentType = "application/json;charset=utf-8";
                         }
                         await context.Response.BodyWriter.WriteAsync(output.ToArray(), context.RequestAborted);

src/OpenApi/src/Services/OpenApiDocumentProvider.cs

@@ -57,7 +57,7 @@ internal sealed class OpenApiDocumentProvider(IServiceProvider serviceProvider)
         using var scopedService = serviceProvider.CreateScope();
         var document = await targetDocumentService.GetOpenApiDocumentAsync(scopedService.ServiceProvider);
         var jsonWriter = new OpenApiJsonWriter(writer);
-        document.Serialize(jsonWriter, openApiSpecVersion);
+        await document.SerializeAsync(jsonWriter, openApiSpecVersion);
     }
 
     /// <summary>

src/OpenApi/src/Services/OpenApiDocumentService.cs

@@ -26,6 +26,7 @@ using Microsoft.Extensions.Hosting;
 using Microsoft.Extensions.Options;
 using Microsoft.Net.Http.Headers;
 using Microsoft.OpenApi.Models;
+using Microsoft.OpenApi.Models.References;
 
 namespace Microsoft.AspNetCore.OpenApi;
 
@@ -59,12 +60,12 @@ internal sealed class OpenApiDocumentService(
         // Schema and operation transformers are scoped per-request and can be
         // pre-allocated to hold the same number of transformers as the associated
         // options object.
-        IOpenApiSchemaTransformer[] schemaTransformers = _options.SchemaTransformers.Count > 0
+        var schemaTransformers = _options.SchemaTransformers.Count > 0
             ? new IOpenApiSchemaTransformer[_options.SchemaTransformers.Count]
-            : Array.Empty<IOpenApiSchemaTransformer>();
-        IOpenApiOperationTransformer[] operationTransformers = _options.OperationTransformers.Count > 0 ?
+            : [];
+        var operationTransformers = _options.OperationTransformers.Count > 0 ?
             new IOpenApiOperationTransformer[_options.OperationTransformers.Count]
-            : Array.Empty<IOpenApiOperationTransformer>();
+            : [];
         InitializeTransformers(scopedServiceProvider, schemaTransformers, operationTransformers);
         var document = new OpenApiDocument
         {
@@ -277,14 +278,7 @@ internal sealed class OpenApiDocumentService(
         IOpenApiSchemaTransformer[] schemaTransformers,
         CancellationToken cancellationToken)
     {
-        var tags = GetTags(description);
-        if (tags != null)
-        {
-            foreach (var tag in tags)
-            {
-                document.Tags?.Add(tag);
-            }
-        }
+        var tags = GetTags(description, document);
         var operation = new OpenApiOperation
         {
             OperationId = GetOperationId(description),
@@ -308,16 +302,27 @@ internal sealed class OpenApiDocumentService(
         => description.ActionDescriptor.AttributeRouteInfo?.Name ??
             description.ActionDescriptor.EndpointMetadata.OfType<IEndpointNameMetadata>().LastOrDefault()?.EndpointName;
 
-    private static List<OpenApiTag>? GetTags(ApiDescription description)
+    private static List<OpenApiTagReference> GetTags(ApiDescription description, OpenApiDocument document)
     {
         var actionDescriptor = description.ActionDescriptor;
         if (actionDescriptor.EndpointMetadata?.OfType<ITagsMetadata>().LastOrDefault() is { } tagsMetadata)
         {
-            return tagsMetadata.Tags.Select(tag => new OpenApiTag { Name = tag }).ToList();
+            List<OpenApiTagReference> tags = [];
+            foreach (var tag in tagsMetadata.Tags)
+            {
+                document.Tags ??= [];
+                document.Tags.Add(new OpenApiTag { Name = tag });
+                tags.Add(new OpenApiTagReference(tag, document));
+
+            }
+            return tags;
         }
         // If no tags are specified, use the controller name as the tag. This effectively
         // allows us to group endpoints by the "resource" concept (e.g. users, todos, etc.)
-        return [new OpenApiTag { Name = description.ActionDescriptor.RouteValues["controller"] }];
+        var controllerName = description.ActionDescriptor.RouteValues["controller"];
+        document.Tags ??= [];
+        document.Tags.Add(new OpenApiTag { Name = controllerName });
+        return [new OpenApiTagReference(controllerName, document)];
     }
 
     private async Task<OpenApiResponses> GetResponsesAsync(

src/OpenApi/src/Services/OpenApiGenerator.cs

@@ -20,6 +20,7 @@ using Microsoft.Extensions.Hosting;
 using Microsoft.Extensions.Internal;
 using Microsoft.Extensions.Primitives;
 using Microsoft.OpenApi.Models;
+using Microsoft.OpenApi.Models.References;
 
 namespace Microsoft.AspNetCore.OpenApi;
 
@@ -322,19 +323,22 @@ internal sealed class OpenApiGenerator
         return null;
     }
 
-    private List<OpenApiTag> GetOperationTags(MethodInfo methodInfo, EndpointMetadataCollection metadata)
+    private List<OpenApiTagReference> GetOperationTags(MethodInfo methodInfo, EndpointMetadataCollection metadata)
     {
         var metadataList = metadata.GetOrderedMetadata<ITagsMetadata>();
+        var document = new OpenApiDocument();
 
         if (metadataList.Count > 0)
         {
-            var tags = new List<OpenApiTag>();
+            var tags = new List<OpenApiTagReference>();
 
             foreach (var metadataItem in metadataList)
             {
                 foreach (var tag in metadataItem.Tags)
                 {
-                    tags.Add(new OpenApiTag() { Name = tag });
+                    document.Tags ??= [];
+                    document.Tags.Add(new OpenApiTag { Name = tag });
+                    tags.Add(new OpenApiTagReference(tag, document));
                 }
             }
 
@@ -354,7 +358,9 @@ internal sealed class OpenApiGenerator
             controllerName = _environment?.ApplicationName ?? string.Empty;
         }
 
-        return new List<OpenApiTag>() { new OpenApiTag() { Name = controllerName } };
+        document.Tags ??= [];
+        document.Tags.Add(new OpenApiTag { Name = controllerName });
+        return [new(controllerName, document)];
     }
 
     private List<OpenApiParameter> GetOpenApiParameters(MethodInfo methodInfo, RoutePattern pattern, bool disableInferredBody)

src/OpenApi/test/Microsoft.AspNetCore.OpenApi.Tests/Integration/snapshots/OpenApiDocumentIntegrationTests.VerifyOpenApiDocument_documentName=controllers.verified.txt

@@ -8,9 +8,7 @@
     "/getbyidandname/{id}/{name}": {
       "get": {
         "tags": [
-          {
-            "name": "Test"
-          }
+          "Test"
         ],
         "parameters": [
           {
@@ -59,9 +57,7 @@
     "/forms": {
       "post": {
         "tags": [
-          {
-            "name": "Test"
-          }
+          "Test"
         ],
         "requestBody": {
           "content": {

src/OpenApi/test/Microsoft.AspNetCore.OpenApi.Tests/Integration/snapshots/OpenApiDocumentIntegrationTests.VerifyOpenApiDocument_documentName=forms.verified.txt

@@ -8,9 +8,7 @@
     "/forms/form-file": {
       "post": {
         "tags": [
-          {
-            "name": "Sample"
-          }
+          "Sample"
         ],
         "requestBody": {
           "content": {
@@ -40,9 +38,7 @@
     "/forms/form-files": {
       "post": {
         "tags": [
-          {
-            "name": "Sample"
-          }
+          "Sample"
         ],
         "requestBody": {
           "content": {
@@ -72,9 +68,7 @@
     "/forms/form-file-multiple": {
       "post": {
         "tags": [
-          {
-            "name": "Sample"
-          }
+          "Sample"
         ],
         "requestBody": {
           "content": {
@@ -118,9 +112,7 @@
     "/forms/form-todo": {
       "post": {
         "tags": [
-          {
-            "name": "Sample"
-          }
+          "Sample"
         ],
         "requestBody": {
           "content": {
@@ -147,9 +139,7 @@
     "/forms/forms-pocos-and-files": {
       "post": {
         "tags": [
-          {
-            "name": "Sample"
-          }
+          "Sample"
         ],
         "requestBody": {
           "content": {

src/OpenApi/test/Microsoft.AspNetCore.OpenApi.Tests/Integration/snapshots/OpenApiDocumentIntegrationTests.VerifyOpenApiDocument_documentName=responses.verified.txt

@@ -8,9 +8,7 @@
     "/responses/200-add-xml": {
       "get": {
         "tags": [
-          {
-            "name": "Sample"
-          }
+          "Sample"
         ],
         "responses": {
           "200": {
@@ -34,9 +32,7 @@
     "/responses/200-only-xml": {
       "get": {
         "tags": [
-          {
-            "name": "Sample"
-          }
+          "Sample"
         ],
         "responses": {
           "200": {
@@ -55,9 +51,7 @@
     "/responses/triangle": {
       "get": {
         "tags": [
-          {
-            "name": "Sample"
-          }
+          "Sample"
         ],
         "responses": {
           "200": {
@@ -76,9 +70,7 @@
     "/responses/shape": {
       "get": {
         "tags": [
-          {
-            "name": "Sample"
-          }
+          "Sample"
         ],
         "responses": {
           "200": {

src/OpenApi/test/Microsoft.AspNetCore.OpenApi.Tests/Integration/snapshots/OpenApiDocumentIntegrationTests.VerifyOpenApiDocument_documentName=schemas-by-ref.verified.txt

@@ -8,9 +8,7 @@
     "/schemas-by-ref/typed-results": {
       "get": {
         "tags": [
-          {
-            "name": "Sample"
-          }
+          "Sample"
         ],
         "responses": {
           "200": {
@@ -29,9 +27,7 @@
     "/schemas-by-ref/multiple-results": {
       "get": {
         "tags": [
-          {
-            "name": "Sample"
-          }
+          "Sample"
         ],
         "responses": {
           "200": {
@@ -60,9 +56,7 @@
     "/schemas-by-ref/iresult-no-produces": {
       "get": {
         "tags": [
-          {
-            "name": "Sample"
-          }
+          "Sample"
         ],
         "responses": {
           "200": {
@@ -74,9 +68,7 @@
     "/schemas-by-ref/iresult-with-produces": {
       "get": {
         "tags": [
-          {
-            "name": "Sample"
-          }
+          "Sample"
         ],
         "responses": {
           "200": {
@@ -95,9 +87,7 @@
     "/schemas-by-ref/primitives": {
       "get": {
         "tags": [
-          {
-            "name": "Sample"
-          }
+          "Sample"
         ],
         "parameters": [
           {
@@ -131,9 +121,7 @@
     "/schemas-by-ref/product": {
       "get": {
         "tags": [
-          {
-            "name": "Sample"
-          }
+          "Sample"
         ],
         "requestBody": {
           "content": {
@@ -162,9 +150,7 @@
     "/schemas-by-ref/account": {
       "get": {
         "tags": [
-          {
-            "name": "Sample"
-          }
+          "Sample"
         ],
         "requestBody": {
           "content": {
@@ -193,9 +179,7 @@
     "/schemas-by-ref/array-of-ints": {
       "post": {
         "tags": [
-          {
-            "name": "Sample"
-          }
+          "Sample"
         ],
         "requestBody": {
           "content": {
@@ -229,9 +213,7 @@
     "/schemas-by-ref/list-of-ints": {
       "post": {
         "tags": [
-          {
-            "name": "Sample"
-          }
+          "Sample"
         ],
         "requestBody": {
           "content": {
@@ -265,9 +247,7 @@
     "/schemas-by-ref/ienumerable-of-ints": {
       "post": {
         "tags": [
-          {
-            "name": "Sample"
-          }
+          "Sample"
         ],
         "responses": {
           "200": {
@@ -287,9 +267,7 @@
     "/schemas-by-ref/dictionary-of-ints": {
       "get": {
         "tags": [
-          {
-            "name": "Sample"
-          }
+          "Sample"
         ],
         "responses": {
           "200": {
@@ -312,9 +290,7 @@
     "/schemas-by-ref/frozen-dictionary-of-ints": {
       "get": {
         "tags": [
-          {
-            "name": "Sample"
-          }
+          "Sample"
         ],
         "responses": {
           "200": {
@@ -337,9 +313,7 @@
     "/schemas-by-ref/shape": {
       "post": {
         "tags": [
-          {
-            "name": "Sample"
-          }
+          "Sample"
         ],
         "requestBody": {
           "content": {
@@ -361,9 +335,7 @@
     "/schemas-by-ref/weatherforecastbase": {
       "post": {
         "tags": [
-          {
-            "name": "Sample"
-          }
+          "Sample"
         ],
         "requestBody": {
           "content": {
@@ -385,9 +357,7 @@
     "/schemas-by-ref/person": {
       "post": {
         "tags": [
-          {
-            "name": "Sample"
-          }
+          "Sample"
         ],
         "requestBody": {
           "content": {

src/OpenApi/test/Microsoft.AspNetCore.OpenApi.Tests/Integration/snapshots/OpenApiDocumentIntegrationTests.VerifyOpenApiDocument_documentName=v1.verified.txt

@@ -8,9 +8,7 @@
     "/v1/array-of-guids": {
       "get": {
         "tags": [
-          {
-            "name": "Sample"
-          }
+          "Sample"
         ],
         "parameters": [
           {
@@ -55,9 +53,7 @@
     "/v1/todos": {
       "post": {
         "tags": [
-          {
-            "name": "Sample"
-          }
+          "Sample"
         ],
         "summary": "Creates a new todo item.",
         "parameters": [
@@ -90,9 +86,7 @@
     "/v1/todos/{id}": {
       "get": {
         "tags": [
-          {
-            "name": "Sample"
-          }
+          "Sample"
         ],
         "description": "Returns a specific todo item.",
         "parameters": [

src/OpenApi/test/Microsoft.AspNetCore.OpenApi.Tests/Integration/snapshots/OpenApiDocumentIntegrationTests.VerifyOpenApiDocument_documentName=v2.verified.txt

@@ -15,9 +15,7 @@
     "/v2/users": {
       "get": {
         "tags": [
-          {
-            "name": "users"
-          }
+          "users"
         ],
         "responses": {
           "200": {
@@ -45,9 +43,7 @@
       },
       "post": {
         "tags": [
-          {
-            "name": "Sample"
-          }
+          "Sample"
         ],
         "externalDocs": {
           "description": "Documentation for this OpenAPI endpoint",

src/OpenApi/test/Microsoft.AspNetCore.OpenApi.Tests/Services/OpenApiDocumentService/OpenApiDocumentServiceTests.Operations.cs

@@ -4,6 +4,7 @@
 using Microsoft.AspNetCore.Builder;
 using Microsoft.AspNetCore.Http;
 using Microsoft.AspNetCore.Mvc;
+using Microsoft.AspNetCore.OpenApi;
 using Microsoft.AspNetCore.Routing;
 using Microsoft.OpenApi.Models;
 
@@ -181,6 +182,62 @@ public partial class OpenApiDocumentServiceTests
         });
     }
 
+    [Fact]
+    public async Task GetOpenApiOperation_EditingReferenceInOperationThrowsException()
+    {
+        // Arrange
+        var builder = CreateBuilder();
+
+        // Act
+        builder.MapGet("/api/todos", () => { }).WithTags(["todos"]);
+        var options = new OpenApiOptions();
+        options.AddOperationTransformer((operation, context, cancellationToken) =>
+        {
+            foreach (var tag in operation.Tags)
+            {
+                tag.Name = "newTag"; // Should throw exception
+            }
+            return Task.CompletedTask;
+        });
+
+        // Assert
+        var exception = await Assert.ThrowsAsync<InvalidOperationException>(() => VerifyOpenApiDocument(builder, options, _ => { }));
+        Assert.Equal("Setting the value from the reference is not supported, use the target property instead.", exception.Message);
+    }
+
+    [Fact]
+    public async Task GetOpenApiOperation_EditingTargetTagInOperationWorks()
+    {
+        // Arrange
+        var builder = CreateBuilder();
+
+        // Act
+        builder.MapGet("/api/todos", () => { }).WithTags(["todos"]);
+        var options = new OpenApiOptions();
+        options.AddOperationTransformer((operation, context, cancellationToken) =>
+        {
+            foreach (var tag in operation.Tags)
+            {
+                tag.Target.Name = "newTag";
+            }
+            return Task.CompletedTask;
+        });
+
+        // Assert
+        await VerifyOpenApiDocument(builder, options, document =>
+        {
+            var operation = document.Paths["/api/todos"].Operations[OperationType.Get];
+            Assert.Collection(operation.Tags, tag =>
+            {
+                Assert.Equal("newTag", tag.Name);
+            });
+            Assert.Collection(document.Tags, tag =>
+            {
+                Assert.Equal("newTag", tag.Name);
+            });
+        });
+    }
+
     [Fact]
     public async Task GetOpenApiOperation_CapturesEndpointNameAsOperationId()
     {

src/Tools/GetDocumentInsider/tests/GetDocumentTests.cs

@@ -66,8 +66,7 @@ public class GetDocumentTests(ITestOutputHelper output)
         // Assert
         using var stream = new MemoryStream(File.ReadAllBytes(Path.Combine(outputPath.FullName, "Sample.json")));
         var result = OpenApiDocument.Load(stream, "json");
-        // TODO: Needs https://github.com/microsoft/OpenAPI.NET/issues/2055 to be fixed
-        // Assert.Empty(result.Diagnostic.Errors);
+        Assert.Empty(result.Diagnostic.Errors);
         Assert.Equal(OpenApiSpecVersion.OpenApi2_0, result.Diagnostic.SpecificationVersion);
         Assert.Equal("GetDocumentSample | v1", result.Document.Info.Title);
     }
@@ -94,8 +93,7 @@ public class GetDocumentTests(ITestOutputHelper output)
         Assert.Contains("Invalid OpenAPI spec version 'OpenApi4_0' provided. Falling back to default: v3.0.", _console.GetOutput());
         using var stream = new MemoryStream(File.ReadAllBytes(Path.Combine(outputPath.FullName, "Sample.json")));
         var result = OpenApiDocument.Load(stream, "json");
-        // TODO: Needs https://github.com/microsoft/OpenAPI.NET/issues/2055 to be fixed
-        // Assert.Empty(result.Diagnostic.Errors);
+        Assert.Empty(result.Diagnostic.Errors);
         Assert.Equal(OpenApiSpecVersion.OpenApi3_1, result.Diagnostic.SpecificationVersion);
         Assert.Equal("GetDocumentSample | v1", result.Document.Info.Title);
     }
@@ -128,8 +126,7 @@ public class GetDocumentTests(ITestOutputHelper output)
 
         using var stream = new MemoryStream(File.ReadAllBytes(Path.Combine(outputPath.FullName, "Sample_internal.json")));
         var result = OpenApiDocument.Load(stream, "json");
-        // TODO: Needs https://github.com/microsoft/OpenAPI.NET/issues/2055 to be fixed
-        // Assert.Empty(result.Diagnostic.Errors);
+        Assert.Empty(result.Diagnostic.Errors);
         Assert.Equal(OpenApiSpecVersion.OpenApi3_1, result.Diagnostic.SpecificationVersion);
         // Document name in the title gives us a clue that the correct document was actually resolved
         Assert.Equal("GetDocumentSample | internal", result.Document.Info.Title);