Skip to content

Navigation Menu

Sign in
Appearance settings

Search code, repositories, users, issues, pull requests...

Provide feedback

We read every piece of feedback, and take your input very seriously.

Saved searches

Use saved searches to filter your results more quickly

Appearance settings

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

Lonli-Lokli started this conversation in General
Discussion options

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

You must be logged in to vote

Replies: 1 comment

Comment options

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.

You must be logged in to vote
0 replies
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
None yet
2 participants
Morty Proxy This is a proxified and sanitized view of the page, visit original site.