Catch-all route parameter should be marked as optional in ApiExplorer

[scharnyw]

Is there an existing issue for this?

• I have searched the existing issues

Describe the bug

Catch-all route parameter is effectively optional because it matches against all values, including whitespace and empty strings. For example, consider the following API:

var builder = WebApplication.CreateBuilder(args);

builder.Services.AddControllers();

var app = builder.Build();

app.MapControllers();

app.Run();

[ApiController]
[Route("")]
public class TestController : ControllerBase
{
    private readonly IApiDescriptionGroupCollectionProvider _apiDescriptionProvider;

    public TestController(IApiDescriptionGroupCollectionProvider apiDescriptionProvider)
    {
        _apiDescriptionProvider = apiDescriptionProvider;
    }

    [HttpGet("{**catchAllParameter}")]
    public IActionResult Get(string catchAllParameter)
    {
        var parameter = _apiDescriptionProvider
            .ApiDescriptionGroups.Items
            .SelectMany(group => group.Items)
            .First(api => api.RelativePath.EndsWith("{catchAllParameter}"))
            .ParameterDescriptions
            .First(parameter => parameter.Name == "catchAllParameter");

        Console.WriteLine(parameter.IsRequired); // true

        return Ok();
    }
}

This API can be reached in any of the following ways:

1. GET / (with or without trailing slash)
2. GET /abc

This behavior of catch-all parameter is consistent with the documentation. It is also consistent between Controllers and Minimal API, except that there is currently a regression bug (#58093) in Minimal API in .NET 8 that prevented it from working (it worked fine in .NET 7).

However, in the above code snippet parameter.IsRequired always reports true. This is effectively a lie because the API can be reached without the parameter being set.

While I understand that ApiExplorer is frequently used for OpenAPI generation purposes, and that the OpenAPI specification does not allow for optional path parameters, I think the ASP.NET Core ApiExplorer's behavior should not be driven solely by OpenAPI. Instead, it should faithfully report the actual API's behavior and let some other component be concerned with OpenAPI compatibility when generating the OpenAPI docs.

Expected Behavior

ApiParameterDescription.IsRequired should report false for catch-all route parameters.

Steps To Reproduce

No response

Exceptions (if any)

No response

.NET Version

8.0.10

Anything else?

No response

[captainsafia]

Thanks for filing this issue!

While I understand that ApiExplorer is frequently used for OpenAPI generation purposes, and that the OpenAPI specification does not allow for optional path parameters, I think the ASP.NET Core ApiExplorer's behavior should not be driven solely by OpenAPI. Instead, it should faithfully report the actual API's behavior and let some other component be concerned with OpenAPI compatibility when generating the OpenAPI docs.

I agree with this sentiment! It seems like you've done a bit og digging int othe space. Would you be interested in submitting a PR?

You'll want to modify the IApiDescriptionProvider interfaces in the repo to react to this change.

We already do the due dilligence in the OpenAPI package to make sure that path parameters are always required so there shouldn't be a need to harden anything there.

[KetchupCodes]

Hi @captainsafia, @martincostello, @mikekistler and @scharnyw ,

I'd like to work on this issue! I've read the description and understand the problem. I'm also grateful for the guidance provided on where to start looking in the codebase.

Would it be possible to assign this issue to me? I'm excited to contribute!

[mapedersen]

I have submitted a PR for this issue: #60544