OpenAPI: Minimal API unused Path parameters are not emitted in the OpenAPI

[desjoerd]

Is there an existing issue for this?

• I have searched the existing issues

Describe the bug

The following unit test fails because the parameters are null.

    [Fact]
    public async Task SupportsUnusedRouteParametersFromMinimalApis()
    {
        var source = """
using System;
using System.Threading.Tasks;
using System.Collections.Generic;
using Microsoft.AspNetCore.Builder;
using Microsoft.Extensions.DependencyInjection;
using Microsoft.AspNetCore.Http;

var builder = WebApplication.CreateBuilder();

builder.Services.AddOpenApi();

var app = builder.Build();

app.MapGet("/{userId}", RouteHandlerExtensionMethods.Get);

app.Run();

public static class RouteHandlerExtensionMethods
{
    /// <param name="userId">The id of the user.</param>
    public static string Get()
    {
        return "Hello, World!";
    }
}
""";

        var generator = new XmlCommentGenerator();
        await SnapshotTestHelper.Verify(source, generator, out var compilation);
        await SnapshotTestHelper.VerifyOpenApi(compilation, document =>
        {
            var path = document.Paths["/{userId}"].Operations[HttpMethod.Get];
            Assert.NotEmpty(path.Parameters);
            Assert.Equal("The id of the user.", path.Parameters[0].Description);
        });
    }

Expected Behavior

The unused path parameter {userId} should be emitted on the operation or on the path as a parameter (that is document.Paths["/{userId}"].Parameters).

Steps To Reproduce

No response

Exceptions (if any)

No response

.NET Version

10.0.100-rc.1.25420.111

Anything else?

Found while fixing #63757

[desjoerd]

This is not related in the OpenAPI support but in the ApiExplorer.

[desjoerd]

When comparing the MVC DefaultApiDescriptionProvider and the EndpointMetadataApiDescriptionProvider the MVC version adds route parameters without any bindings in the DefaultApiDescriptionProvider.ProcessRouteParameters method

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

Lines 284 to 294 in a8a4f36

	// Lastly, create a parameter representation for each route parameter that did not find
	// a partner.
	foreach (var routeParameter in routeParameters)
	{
	context.Results.Add(new ApiParameterDescription()
	{
	Name = routeParameter.Key,
	RouteInfo = routeParameter.Value,
	Source = BindingSource.Path,
	});
	}

This does not happen within the EndpointMetadataApiDescriptionProvider. This doesn't go over the route parameters without IParameterBindingMetadata

aspnetcore/src/Mvc/Mvc.ApiExplorer/src/EndpointMetadataApiDescriptionProvider.cs

Lines 116 to 130 in a8a4f36

	var parameters = routeEndpoint.Metadata.GetOrderedMetadata<IParameterBindingMetadata>();
	foreach (var parameter in parameters)
	{
	var parameterDescription = CreateApiParameterDescription(parameter, routeEndpoint, disableInferredBody);
	if (parameterDescription is { })
	{
	apiDescription.ParameterDescriptions.Add(parameterDescription);
	hasBodyOrFormFileParameter |=
	parameterDescription.Source == BindingSource.Body ||
	parameterDescription.Source == BindingSource.FormFile;
	}
	}

(Route) Parameters which aren't defined in the endpoint will not get a IParameterBindingMetadata as there is no binding.

Constructing IParameterBindingMetadata for route values which aren't used is not going to match the nullability in IParameterBindingMetadata

aspnetcore/src/Http/Http.Abstractions/src/Metadata/IParameterBindingMetadata.cs

Lines 17 to 43 in a8a4f36

	public interface IParameterBindingMetadata
	{
	/// <summary>
	/// The name of the parameter.
	/// </summary>
	string Name { get; }
	/// <summary>
	/// <see langword="true "/> is the parameter is associated with a type that implements <see cref="IParsable{TSelf}" /> or exposes a <c>TryParse</c> method.
	/// </summary>
	bool HasTryParse { get; }
	/// <summary>
	/// <see langword="true"/> if the parameter is associated with a type that implements a <c>BindAsync</c> method.
	/// </summary>
	bool HasBindAsync { get; }
	/// <summary>
	/// The <see cref="ParameterInfo"/> associated with the parameter.
	/// </summary>
	ParameterInfo ParameterInfo { get; }
	/// <summary>
	/// <see langword="true"/> if the parameter is optional.
	/// </summary>
	bool IsOptional { get; }
	}

as ParameterInfo is not nullable and the parameter does not exist.

So I think the solution would be to add special handling of adding route parameters to the ApiDescriptor.

For MVC the ModelMeta on the ApiParameterDescription is null for route parameters which do not have a binding. The same would happen if we add this fix for the EndpointMetadataApiDescriptionProvider. It does not match the nullability on the ApiParameterDescription. This is an existing issue:

aspnetcore/src/Mvc/Mvc.Abstractions/src/ApiExplorer/ApiParameterDescription.cs

Lines 9 to 18 in a8a4f36

	/// <summary>
	/// A metadata description of an input to an API.
	/// </summary>
	public class ApiParameterDescription
	{
	/// <summary>
	/// Gets or sets the <see cref="ModelMetadata"/>.
	/// </summary>
	public ModelMetadata ModelMetadata { get; set; } = default!;

If the owner around the ApiExplorer agrees with adding special handling for not bound route parameters in the EndpointMetadataApiDescriptionProvider I would gladly like to help on this.

[desjoerd]

I could not help it so I just went ahead with the fix 😅. It's my own fault when it's not the desired direction 🙈.