-
Notifications
You must be signed in to change notification settings - Fork 714
Future of OpenAPI tags (Summary, Description) with Minimal API #959
-
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
Beta Was this translation helpful? Give feedback.
All reactions
Replies: 1 comment
-
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.
Beta Was this translation helpful? Give feedback.