Add OpenApiVersionSelector

See dotnet#62193 (comment)

Author: martincostello

src/OpenApi/sample/Program.cs

@@ -21,13 +21,26 @@
     options.SerializerOptions.NumberHandling = JsonNumberHandling.Strict;
 });
 
+Func<HttpContext, OpenApiSpecVersion?> versionSelector = (context) =>
+{
+    if (context.Request.Query["version"] is { Count: 1 } version &&
+        Enum.TryParse<OpenApiSpecVersion>(version, out var result))
+    {
+        return result;
+    }
+
+    return null;
+};
+
 builder.Services.AddOpenApi("v1", options =>
 {
+    options.OpenApiVersionSelector = versionSelector;
     options.AddHeader("X-Version", "1.0");
     options.AddDocumentTransformer<BearerSecuritySchemeTransformer>();
 });
 builder.Services.AddOpenApi("v2", options =>
 {
+    options.OpenApiVersionSelector = versionSelector;
     options.AddSchemaTransformer<AddExternalDocsTransformer>();
     options.AddOperationTransformer<AddExternalDocsTransformer>();
     options.AddDocumentTransformer(new AddContactTransformer());
@@ -53,37 +66,9 @@
     "xml",
 };
 
-foreach (var version in versions)
+foreach (var name in documentNames)
 {
-    builder.Services.AddOpenApi($"v1-{version}", options =>
-    {
-        options.OpenApiVersion = version;
-        options.ShouldInclude = (description) => description.GroupName == null || description.GroupName == "v1";
-        options.AddHeader("X-Version", "1.0");
-        options.AddDocumentTransformer<BearerSecuritySchemeTransformer>();
-    });
-    builder.Services.AddOpenApi($"v2-{version}", options =>
-    {
-        options.OpenApiVersion = version;
-        options.ShouldInclude = (description) => description.GroupName == null || description.GroupName == "v2";
-        options.AddSchemaTransformer<AddExternalDocsTransformer>();
-        options.AddOperationTransformer<AddExternalDocsTransformer>();
-        options.AddDocumentTransformer(new AddContactTransformer());
-        options.AddDocumentTransformer((document, context, token) =>
-        {
-            document.Info.License = new OpenApiLicense { Name = "MIT" };
-            return Task.CompletedTask;
-        });
-    });
-
-    foreach (var name in documentNames)
-    {
-        builder.Services.AddOpenApi($"{name}-{version}", options =>
-        {
-            options.OpenApiVersion = version;
-            options.ShouldInclude = (description) => description.GroupName == null || description.GroupName == name;
-        });
-    }
+    builder.Services.AddOpenApi(name, (options) => options.OpenApiVersionSelector = versionSelector);
 }
 
 var app = builder.Build();

src/OpenApi/src/Extensions/OpenApiEndpointRouteBuilderExtensions.cs

@@ -8,6 +8,7 @@
 using Microsoft.AspNetCore.Routing;
 using Microsoft.Extensions.DependencyInjection;
 using Microsoft.Extensions.Options;
+using Microsoft.OpenApi;
 using Microsoft.OpenApi.Extensions;
 using Microsoft.OpenApi.Writers;
 
@@ -53,6 +54,7 @@ public static IEndpointConventionBuilder MapOpenApi(this IEndpointRouteBuilder e
                 {
                     var document = await documentService.GetOpenApiDocumentAsync(context.RequestServices, context.Request, context.RequestAborted);
                     var documentOptions = options.Get(lowercasedDocumentName);
+                    var openApiVersion = documentOptions.OpenApiVersionSelector?.Invoke(context) ?? documentOptions.OpenApiVersion;
 
                     using var textWriter = new Utf8BufferTextWriter(System.Globalization.CultureInfo.InvariantCulture);
                     textWriter.SetWriter(context.Response.BodyWriter);
@@ -74,7 +76,7 @@ public static IEndpointConventionBuilder MapOpenApi(this IEndpointRouteBuilder e
                     context.Response.ContentType = contentType;
 
                     await context.Response.StartAsync();
-                    await document.SerializeAsync(openApiWriter, documentOptions.OpenApiVersion, context.RequestAborted);
+                    await document.SerializeAsync(openApiWriter, openApiVersion, context.RequestAborted);
                     await context.Response.BodyWriter.FlushAsync(context.RequestAborted);
                 }
             }).ExcludeFromDescription();

src/OpenApi/src/PublicAPI.Unshipped.txt

@@ -1,6 +1,8 @@
 #nullable enable
 Microsoft.AspNetCore.OpenApi.IOpenApiDocumentProvider
 Microsoft.AspNetCore.OpenApi.IOpenApiDocumentProvider.GetOpenApiDocumentAsync(System.Threading.CancellationToken cancellationToken = default(System.Threading.CancellationToken)) -> System.Threading.Tasks.Task<Microsoft.OpenApi.Models.OpenApiDocument!>!
+Microsoft.AspNetCore.OpenApi.OpenApiOptions.OpenApiVersionSelector.get -> System.Func<Microsoft.AspNetCore.Http.HttpContext!, Microsoft.OpenApi.OpenApiSpecVersion?>?
+Microsoft.AspNetCore.OpenApi.OpenApiOptions.OpenApiVersionSelector.set -> void
 static Microsoft.AspNetCore.Builder.OpenApiEndpointConventionBuilderExtensions.AddOpenApiOperationTransformer<TBuilder>(this TBuilder builder, System.Func<Microsoft.OpenApi.Models.OpenApiOperation!, Microsoft.AspNetCore.OpenApi.OpenApiOperationTransformerContext!, System.Threading.CancellationToken, System.Threading.Tasks.Task!>! transformer) -> TBuilder
 Microsoft.AspNetCore.OpenApi.OpenApiDocumentTransformerContext.GetOrCreateSchemaAsync(System.Type! type, Microsoft.AspNetCore.Mvc.ApiExplorer.ApiParameterDescription? parameterDescription = null, System.Threading.CancellationToken cancellationToken = default(System.Threading.CancellationToken)) -> System.Threading.Tasks.Task<Microsoft.OpenApi.Models.OpenApiSchema!>!
 Microsoft.AspNetCore.OpenApi.OpenApiOperationTransformerContext.Document.get -> Microsoft.OpenApi.Models.OpenApiDocument?

src/OpenApi/src/Services/OpenApiOptions.cs

@@ -3,6 +3,7 @@
 
 using System.Diagnostics.CodeAnalysis;
 using System.Text.Json.Serialization.Metadata;
+using Microsoft.AspNetCore.Http;
 using Microsoft.AspNetCore.Mvc.ApiExplorer;
 using Microsoft.OpenApi;
 using Microsoft.OpenApi.Models;
@@ -39,6 +40,11 @@ public OpenApiOptions()
     /// </summary>
     public OpenApiSpecVersion OpenApiVersion { get; set; } = OpenApiSpecVersion.OpenApi3_1;
 
+    /// <summary>
+    /// An optional delegate to determine the OpenAPI version to use for the current HTTP request.
+    /// </summary>
+    public Func<HttpContext, OpenApiSpecVersion?>? OpenApiVersionSelector { get; set; }
+
     /// <summary>
     /// The name of the OpenAPI document this <see cref="OpenApiOptions"/> instance is associated with.
     /// </summary>

src/OpenApi/test/Microsoft.AspNetCore.OpenApi.Tests/Integration/OpenApiDocumentIntegrationTests.cs

@@ -37,7 +37,7 @@ public async Task VerifyOpenApiDocument(string documentName, OpenApiSpecVersion
     {
         var versionString = version.ToString();
         using var client = fixture.CreateClient();
-        var json = await client.GetStringAsync($"/openapi/{documentName}-{versionString}.json");
+        var json = await client.GetStringAsync($"/openapi/{documentName}.json?version={versionString}");
         var baseSnapshotsDirectory = SkipOnHelixAttribute.OnHelix()
             ? Path.Combine(Environment.GetEnvironmentVariable("HELIX_WORKITEM_ROOT"), "Integration", "snapshots")
             : "snapshots";

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

@@ -1,7 +1,7 @@
 {
   "openapi": "3.0.4",
   "info": {
-    "title": "Sample | controllers-openapi3_0",
+    "title": "Sample | controllers",
     "version": "1.0.0"
   },
   "servers": [

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

@@ -1,7 +1,7 @@
 {
   "openapi": "3.0.4",
   "info": {
-    "title": "Sample | forms-openapi3_0",
+    "title": "Sample | forms",
     "version": "1.0.0"
   },
   "servers": [

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

@@ -1,7 +1,7 @@
 {
   "openapi": "3.0.4",
   "info": {
-    "title": "Sample | responses-openapi3_0",
+    "title": "Sample | responses",
     "version": "1.0.0"
   },
   "servers": [

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

@@ -1,7 +1,7 @@
 {
   "openapi": "3.0.4",
   "info": {
-    "title": "Sample | schemas-by-ref-openapi3_0",
+    "title": "Sample | schemas-by-ref",
     "version": "1.0.0"
   },
   "servers": [

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

@@ -1,7 +1,7 @@
 {
   "openapi": "3.0.4",
   "info": {
-    "title": "Sample | v1-openapi3_0",
+    "title": "Sample | v1",
     "version": "1.0.0"
   },
   "servers": [