feat: Swagger improvements (Retargeted)

src/Umbraco.Cms.Api.Common/Configuration/ConfigureUmbracoSwaggerGenOptions.cs

@@ -5,6 +5,7 @@
 using Microsoft.Extensions.Options;
 using Microsoft.OpenApi.Models;
 using Swashbuckle.AspNetCore.SwaggerGen;
+using Umbraco.Cms.Api.Common.Attributes;
 using Umbraco.Cms.Api.Common.OpenApi;
 using Umbraco.Cms.Core.DependencyInjection;
 using Umbraco.Extensions;
@@ -46,29 +47,90 @@ public void Configure(SwaggerGenOptions swaggerGenOptions)
             });
 
         swaggerGenOptions.CustomOperationIds(description => _operationIdSelector.OperationId(description));
-        swaggerGenOptions.DocInclusionPredicate((name, api) =>
+        swaggerGenOptions.DocInclusionPredicate((documentGroupName, apiDescription) =>
         {
-            if (string.IsNullOrWhiteSpace(api.GroupName))
+            if (apiDescription.ActionDescriptor is ControllerActionDescriptor controllerActionDescriptor)
             {
-                return false;
+                MapToApiAttribute? mapToApiAttribute = controllerActionDescriptor.MethodInfo.GetMapToApiAttribute();
+
+                if (mapToApiAttribute != null)
+                {
+                    return mapToApiAttribute.ApiName == documentGroupName;
+                }
+            }
+
+            if (string.IsNullOrWhiteSpace(apiDescription.GroupName))
+            {
+                return documentGroupName == DefaultApiConfiguration.ApiName;
             }
 
-            if (api.ActionDescriptor is ControllerActionDescriptor controllerActionDescriptor)
+            if (documentGroupName == apiDescription.GroupName)
             {
-                return controllerActionDescriptor.MethodInfo.HasMapToApiAttribute(name);
+                return true;
             }
 
-            return false;
+            IOptions<SwaggerGenOptions> swaggerOptions = StaticServiceProvider.Instance.GetRequiredService<IOptions<SwaggerGenOptions>>();
+            if (swaggerOptions.Value.SwaggerGeneratorOptions.SwaggerDocs.ContainsKey(apiDescription.GroupName))
+            {
+                return false;
+            }
+            else
+            {
+                return documentGroupName == DefaultApiConfiguration.ApiName;
+            }
         });
-        swaggerGenOptions.TagActionsBy(api => new[] { api.GroupName });
+
+        swaggerGenOptions.TagActionsBy(TagActionsBy);
         swaggerGenOptions.OrderActionsBy(ActionOrderBy);
         swaggerGenOptions.SchemaFilter<EnumSchemaFilter>();
         swaggerGenOptions.CustomSchemaIds(_schemaIdSelector.SchemaId);
         swaggerGenOptions.SelectSubTypesUsing(_subTypesSelector.SubTypes);
         swaggerGenOptions.SupportNonNullableReferenceTypes();
     }
 
+    private static List<string> TagActionsBy(ApiDescription apiDescription)
+    {
+        if (apiDescription.GroupName != null)
+        {
+            return new List<string> { apiDescription.GroupName };
+        }
+
+        return new List<string>();
+    }
+
     // see https://github.com/domaindrivendev/Swashbuckle.AspNetCore#change-operation-sort-order-eg-for-ui-sorting
-    private static string ActionOrderBy(ApiDescription apiDesc)
-        => $"{apiDesc.GroupName}_{apiDesc.ActionDescriptor.AttributeRouteInfo?.Template ?? apiDesc.ActionDescriptor.RouteValues["controller"]}_{apiDesc.ActionDescriptor.RouteValues["action"]}_{apiDesc.HttpMethod}";
+    private static string ActionOrderBy(ApiDescription apiDescription)
+    {
+        var orderBySections = new List<string>();
+
+        if (apiDescription.GroupName != null)
+        {
+            orderBySections.Add(apiDescription.GroupName);
+        }
+        else
+        {
+            orderBySections.Add(DefaultApiConfiguration.ApiName);
+        }
+
+        if (apiDescription.ActionDescriptor.AttributeRouteInfo?.Template != null)
+        {
+            orderBySections.Add(apiDescription.ActionDescriptor.AttributeRouteInfo.Template);
+        }
+        else if (apiDescription.ActionDescriptor.RouteValues.TryGetValue("controller", out string? controllerValue) && !string.IsNullOrEmpty(controllerValue))
+        {
+            orderBySections.Add(controllerValue);
+        }
+
+        if (apiDescription.ActionDescriptor.RouteValues.TryGetValue("action", out string? actionValue) && !string.IsNullOrEmpty(actionValue))
+        {
+            orderBySections.Add(actionValue);
+        }
+
+        if (apiDescription.HttpMethod != null)
+        {
+            orderBySections.Add(apiDescription.HttpMethod);
+        }
+
+        return string.Join('_', orderBySections);
+    }
 }

src/Umbraco.Cms.Api.Common/DependencyInjection/UmbracoBuilderApiExtensions.cs

@@ -16,6 +16,7 @@ public static IUmbracoBuilder AddUmbracoApiOpenApiUI(this IUmbracoBuilder builde
             return builder;
         }
 
+        builder.Services.AddEndpointsApiExplorer();
         builder.Services.AddSwaggerGen();
         builder.Services.ConfigureOptions<ConfigureUmbracoSwaggerGenOptions>();
         builder.Services.AddSingleton<IUmbracoJsonTypeInfoResolver, UmbracoJsonTypeInfoResolver>();

src/Umbraco.Cms.Api.Common/Extensions/MethodInfoApiCommonExtensions.cs

@@ -15,18 +15,21 @@ public static class MethodInfoApiCommonExtensions
         return string.Join("|", mapToApis.SelectMany(x=>x.Versions));
     }
 
-    public static string? GetMapToApiAttributeValue(this MethodInfo methodInfo)
-    {
-        MapToApiAttribute[] mapToApis = (methodInfo.DeclaringType?.GetCustomAttributes(typeof(MapToApiAttribute), inherit: true) ?? Array.Empty<object>()).Cast<MapToApiAttribute>().ToArray();
+    public static MapToApiAttribute? GetMapToApiAttribute(this MethodInfo methodInfo) => methodInfo.DeclaringType?.GetCustomAttributes<MapToApiAttribute>(inherit: true).SingleOrDefault();
 
-        return mapToApis.SingleOrDefault()?.ApiName;
-    }
+    [Obsolete("Use GetMapToApiAttribute instead and get the value from .ApiName")]
+    public static string? GetMapToApiAttributeValue(this MethodInfo methodInfo) => GetMapToApiAttribute(methodInfo)?.ApiName;
 
+    [Obsolete("Use GetMapToApiAttribute instead.")]
     public static bool HasMapToApiAttribute(this MethodInfo methodInfo, string apiName)
     {
-        var value = methodInfo.GetMapToApiAttributeValue();
+        MapToApiAttribute? mapToApiAttribute = GetMapToApiAttribute(methodInfo);
+
+        if (mapToApiAttribute is null)
+        {
+            return apiName == DefaultApiConfiguration.ApiName;
+        }
 
-        return value == apiName
-               || (value is null && apiName == DefaultApiConfiguration.ApiName);
+        return mapToApiAttribute.ApiName == apiName;
     }
 }