Fix: Mark catch-all route parameters as optional (#60392) (#60544)

* Fix: Mark catch-all route parameters as optional (#60392)

- Added a unit test in DefaultApiDescriptionProviderTest to validate that catch-all route parameters (e.g., "{**catchAllParameter}") are reported as optional.
- Modified ProcessIsRequired in DefaultApiDescriptionProvider to detect catch-all parameters (by checking for the "{**" pattern in the route template) and mark them as not required.
- This change aligns ApiExplorer metadata with the actual runtime behavior, ensuring more accurate API documentation.
- Follows TDD practices by first writing a failing test and then implementing the fix.

* Fix: Use route parameter metadata to correctly mark catch-all parameters as optional

Previously, ApiExplorer marked all parameters as optional if the route template contained a catch-all marker ("{**"). This update refines the logic by leveraging ApiParameterContext.RouteParameters and the IsCatchAll flag to identify and mark only the catch-all parameter as optional. This change aligns the API metadata with the actual routing semantics and addresses #60392.

Author: mapedersen

src/Mvc/Mvc.ApiExplorer/src/DefaultApiDescriptionProvider.cs

@@ -315,9 +315,21 @@ internal static void ProcessIsRequired(ApiParameterContext context, MvcOptions m
                 parameter.IsRequired = true;
             }
 
-            if (parameter.Source == BindingSource.Path && parameter.RouteInfo != null && !parameter.RouteInfo.IsOptional)
+            if (parameter.Source == BindingSource.Path && parameter.RouteInfo != null)
             {
-                parameter.IsRequired = true;
+                // Locate the corresponding route parameter metadata.
+                var routeParam = context.RouteParameters
+                    .FirstOrDefault(rp => string.Equals(rp.Name, parameter.Name, StringComparison.OrdinalIgnoreCase));
+
+                // If the parameter is defined as a catch-all, mark it as optional.
+                if (routeParam != null && routeParam.IsCatchAll)
+                {
+                    parameter.IsRequired = false;
+                }
+                else if (!parameter.RouteInfo.IsOptional)
+                {
+                    parameter.IsRequired = true;
+                }
             }
         }
     }

src/Mvc/Mvc.ApiExplorer/test/DefaultApiDescriptionProviderTest.cs

@@ -32,6 +32,36 @@ namespace Microsoft.AspNetCore.Mvc.Description;
 
 public class DefaultApiDescriptionProviderTest
 {
+    [Fact]
+    public void OnlyCatchAllParameter_IsReportedAsOptional()
+    {
+        // Arrange: Create an action descriptor with a multi-parameter route template.
+        var action = CreateActionDescriptor();
+        action.AttributeRouteInfo = new AttributeRouteInfo
+        {
+            Template = "/products/{category}/items/{group}/inventory/{**any}"
+        };
+
+        // Act: Get the API descriptions using the existing helper.
+        var descriptions = GetApiDescriptions(action);
+
+        // Assert: Only the 'any' parameter should be optional.
+        var description = Assert.Single(descriptions);
+        var categoryParameter = Assert.Single(description.ParameterDescriptions,
+            p => string.Equals(p.Name, "category", StringComparison.OrdinalIgnoreCase));
+        var groupParameter = Assert.Single(description.ParameterDescriptions,
+            p => string.Equals(p.Name, "group", StringComparison.OrdinalIgnoreCase));
+        var anyParameter = Assert.Single(description.ParameterDescriptions,
+            p => string.Equals(p.Name, "any", StringComparison.OrdinalIgnoreCase));
+
+        // The non-catch-all parameters should be required.
+        Assert.True(categoryParameter.IsRequired);
+        Assert.True(groupParameter.IsRequired);
+
+        // The catch-all parameter should be optional.
+        Assert.False(anyParameter.IsRequired);
+    }
+
     [Fact]
     public void GetApiDescription_IgnoresNonControllerActionDescriptor()
     {