Add support for custom group name formatting

Author: commonsensesoftware

src/AspNetCore/WebApi/src/Asp.Versioning.Mvc.ApiExplorer/ApiExplorerOptions.cs

@@ -46,4 +46,13 @@ public IApiVersionParameterSource ApiVersionParameterSource
     /// </summary>
     /// <value>The name associated with the <see cref="ApiVersionRouteConstraint">API version route constraint</see>.</value>
     public string RouteConstraintName { get; set; } = string.Empty;
+
+    /// <summary>
+    /// Gets or sets the function used to format the combination of a group name and API version.
+    /// </summary>
+    /// <value>The <see cref="FormatGroupNameCallback">callback</see> used to format the combination of
+    /// a group name and API version. The default value is <c>null</c>.</value>
+    /// <remarks>The specified callback will only be invoked if a group name has been configured. The API
+    /// version will be provided formatted according to the <see cref="GroupNameFormat">group name format</see>.</remarks>
+    public FormatGroupNameCallback? FormatGroupName { get; set; }
 }

src/AspNetCore/WebApi/src/Asp.Versioning.Mvc.ApiExplorer/ApiVersionDescriptionProviderFactory.cs

@@ -0,0 +1,32 @@
+// Copyright (c) .NET Foundation and contributors. All rights reserved.
+
+namespace Microsoft.AspNetCore.Builder;
+
+using Asp.Versioning;
+using Asp.Versioning.ApiExplorer;
+using Microsoft.AspNetCore.Mvc.Infrastructure;
+using Microsoft.AspNetCore.Routing;
+using Microsoft.Extensions.DependencyInjection;
+using Microsoft.Extensions.Options;
+
+internal sealed class ApiVersionDescriptionProviderFactory : IApiVersionDescriptionProviderFactory
+{
+    private readonly IServiceProvider serviceProvider;
+    private readonly Func<EndpointDataSource, IActionDescriptorCollectionProvider, ISunsetPolicyManager, IOptions<ApiExplorerOptions>, IApiVersionDescriptionProvider> activator;
+
+    public ApiVersionDescriptionProviderFactory(
+        IServiceProvider serviceProvider,
+        Func<EndpointDataSource, IActionDescriptorCollectionProvider, ISunsetPolicyManager, IOptions<ApiExplorerOptions>, IApiVersionDescriptionProvider> activator )
+    {
+        this.serviceProvider = serviceProvider;
+        this.activator = activator;
+    }
+
+    public IApiVersionDescriptionProvider Create( EndpointDataSource endpointDataSource )
+    {
+        var actionDescriptorCollectionProvider = serviceProvider.GetRequiredService<IActionDescriptorCollectionProvider>();
+        var sunsetPolicyManager = serviceProvider.GetRequiredService<ISunsetPolicyManager>();
+        var options = serviceProvider.GetRequiredService<IOptions<ApiExplorerOptions>>();
+        return activator( endpointDataSource, actionDescriptorCollectionProvider, sunsetPolicyManager, options );
+    }
+}

src/AspNetCore/WebApi/src/Asp.Versioning.Mvc.ApiExplorer/DependencyInjection/IApiVersioningBuilderExtensions.cs

@@ -4,7 +4,9 @@ namespace Microsoft.Extensions.DependencyInjection;
 
 using Asp.Versioning;
 using Asp.Versioning.ApiExplorer;
+using Microsoft.AspNetCore.Builder;
 using Microsoft.AspNetCore.Mvc.ApiExplorer;
+using Microsoft.AspNetCore.Mvc.Infrastructure;
 using Microsoft.AspNetCore.Mvc.ModelBinding;
 using Microsoft.AspNetCore.Routing;
 using Microsoft.Extensions.DependencyInjection.Extensions;
@@ -61,7 +63,8 @@ private static void AddApiExplorerServices( IServiceCollection services )
 
         services.AddMvcCore().AddApiExplorer();
         services.TryAddSingleton<IOptionsFactory<ApiExplorerOptions>, ApiExplorerOptionsFactory<ApiExplorerOptions>>();
-        services.TryAddSingleton<IApiVersionDescriptionProvider, DefaultApiVersionDescriptionProvider>();
+        services.TryAddTransient( ResolveApiVersionDescriptionProviderFactory );
+        services.TryAddSingleton( ResolveApiVersionDescriptionProvider );
 
         // use internal constructor until ASP.NET Core fixes their bug
         // BUG: https://github.com/dotnet/aspnetcore/issues/41773
@@ -73,4 +76,50 @@ private static void AddApiExplorerServices( IServiceCollection services )
                     sp.GetRequiredService<IInlineConstraintResolver>(),
                     sp.GetRequiredService<IOptions<ApiExplorerOptions>>() ) ) );
     }
+
+    private static IApiVersionDescriptionProviderFactory ResolveApiVersionDescriptionProviderFactory( IServiceProvider serviceProvider )
+    {
+        var options = serviceProvider.GetRequiredService<IOptions<ApiExplorerOptions>>();
+        var mightUseCustomGroups = options.Value.FormatGroupName is not null;
+
+        return new ApiVersionDescriptionProviderFactory( serviceProvider, mightUseCustomGroups ? NewGroupedProvider : NewDefaultProvider );
+
+        static IApiVersionDescriptionProvider NewDefaultProvider(
+            EndpointDataSource endpointDataSource,
+            IActionDescriptorCollectionProvider actionDescriptorCollectionProvider,
+            ISunsetPolicyManager sunsetPolicyManager,
+            IOptions<ApiExplorerOptions> apiExplorerOptions ) =>
+            new DefaultApiVersionDescriptionProvider( endpointDataSource, actionDescriptorCollectionProvider, sunsetPolicyManager, apiExplorerOptions );
+
+        static IApiVersionDescriptionProvider NewGroupedProvider(
+            EndpointDataSource endpointDataSource,
+            IActionDescriptorCollectionProvider actionDescriptorCollectionProvider,
+            ISunsetPolicyManager sunsetPolicyManager,
+            IOptions<ApiExplorerOptions> apiExplorerOptions ) =>
+            new GroupedApiVersionDescriptionProvider( endpointDataSource, actionDescriptorCollectionProvider, sunsetPolicyManager, apiExplorerOptions );
+    }
+
+    private static IApiVersionDescriptionProvider ResolveApiVersionDescriptionProvider( IServiceProvider serviceProvider )
+    {
+        var endpointDataSource = serviceProvider.GetRequiredService<EndpointDataSource>();
+        var actionDescriptorCollectionProvider = serviceProvider.GetRequiredService<IActionDescriptorCollectionProvider>();
+        var sunsetPolicyManager = serviceProvider.GetRequiredService<ISunsetPolicyManager>();
+        var options = serviceProvider.GetRequiredService<IOptions<ApiExplorerOptions>>();
+        var mightUseCustomGroups = options.Value.FormatGroupName is not null;
+
+        if ( mightUseCustomGroups )
+        {
+            return new GroupedApiVersionDescriptionProvider(
+                endpointDataSource,
+                actionDescriptorCollectionProvider,
+                sunsetPolicyManager,
+                options );
+        }
+
+        return new DefaultApiVersionDescriptionProvider(
+            endpointDataSource,
+            actionDescriptorCollectionProvider,
+            sunsetPolicyManager,
+            options );
+    }
 }

src/AspNetCore/WebApi/src/Asp.Versioning.Mvc.ApiExplorer/FormatGroupNameCallback.cs

@@ -0,0 +1,11 @@
+// Copyright (c) .NET Foundation and contributors. All rights reserved.
+
+namespace Asp.Versioning.ApiExplorer;
+
+/// <summary>
+/// Represents a callback function used to format a group name.
+/// </summary>
+/// <param name="groupName">The associated group name.</param>
+/// <param name="apiVersion">A formatted API version.</param>
+/// <returns>The format result.</returns>
+public delegate string FormatGroupNameCallback( string groupName, string apiVersion );