Future of OpenAPI tags (Summary, Description) with Minimal API

[Lonli-Lokli]

Assuming that we have a Minimal API growing, what are the options for extending support of documentation with it for OpenAPI?
Earlier it was possible to add commend to Controller method and see this description in the Swagger page near to the action

[commonsensesoftware]

This is still supported albeit in a slightly different way. The IEndpointDescriptionMetadata enables configuring a description and IEndpointSummaryMetadata enables configuring a summary. These can be set via the extension methods WithDescription and WithSummary respectively. For example:

builder.MapGet("/hello", () => Results.Ok).WithDescription("A description").WithSummary("A summary");

The larger problem is that the API Explorer does not have a place for this metadata to go (as I recall). This means that even it's configured, it will not auto-magically show up. OpenAPI generators like Swashbuckle have dealt with this problem other ways; for example, using the XML Comments (which Minimal APIs naturally do not have).

Fear not! Not all is lost. If you configure this metadata, it's available, but you have to connect the dots on your own. In Swashbuckle, this can be achieved with an IOperationFilter like so:

public void Apply( OpenApiOperation operation, OperationFilterContext context )
{
    var apiDescription = context.ApiDescription;
    var metadata = apiDescription.ActionDescriptor.EndpointMetadata;

    operation.Description ??= metadata.OfType<IEndpointDescriptionMetadata>().FirstOrDefault()?.Description;
    operation.Summary ??= metadata.OfType<IEndpointSummaryMetadata>().FirstOrDefault()?.Summary;
}

Since the API Explorer doesn't seem to have a simpler way to provide this information and API Versioning doesn't directly depend on any OpenAPI libraries, I'm not sure how else this gap can be bridged - for now. I have had some discussions with the ASP.NET team and we're hoping to have a better story in .NET 8. The API Explorer either needs to handle the known gaps or a new OpenAPI-specific library needs to supplant it.

It is worth noting that you cannot use the WithOpenApi extension method. This will break the API Versioning exploration extensions. This happens because an OpenApiOperation is directly attached as metadata and results in some OpenAPI generators bypassing all the work that API Versioning did during API exploration. TL;DR, there's a lot more detail and background on this topic in #953.