Reduce reliance on ApiExplorer types for Microsoft.AspNetCore.OpenApi consumption

[captainsafia]

In .NET 7, we introduced the new Microsoft.AspNetCore.OpenApi package that generates an OpenApiOperation definition for a given minimal endpoint and its metadata. One of the goals of this package was to remove the reliance on ApiExplorer and it's types that existed in the current implementation for OpenAPI definitions.

Currently, even if a user is using WithOpenApi exclusively to document their endpoints they still have to include the following in their application to register the minimal API-specific implementations of ApiExplorer.

builder.Services.AddEndpointsApiExplorer();

Open source dependencies like Swashbuckle and NSwag still rely on ApiExplorer-specific types, like IApiDescriptionGroupCollectionProvider, to determine all of the endpoints that are associated with an application. Reducing the reliance on this type for minimal API scenarios in particular would allow us to remove the AddEndpointsApiExplorer from the template.

There's a chance that if we do #44192, then we wouldn't need to find a different way to derive all the endpoints in an application and can instead use the OpenApiDocument directly as the source of truth.

[ghost]

Thanks for contacting us.

We're moving this issue to the .NET 8 Planning milestone for future evaluation / consideration. We would like to keep this around to collect more feedback, which can help us with prioritizing this work. We will re-evaluate this issue, during our next planning meeting(s).
If we later determine, that the issue has no community involvement, or it's very rare and low-impact issue, we will close it - so that the team can focus on more important and high impact issues.
To learn more about what to expect next and how this issue will be handled you can read more about our triage process here.

[davidfowl]

I would also like to bring up the fact that all endpoints are opt into open API by default because of this. If we design a new way I like the explicit opt in via an explicit call to WithOpenApi. Using groups, you can also apply that to many endpoints without much hassle. It's a much cleaner way to enable things.

[captainsafia]

I would also like to bring up the fact that all endpoints are opt into open API by default because of this. If we design a new way I like the explicit opt in via an explicit call to WithOpenApi. Using groups, you can also apply that to many endpoints without much hassle. It's a much cleaner way to enable things.

Agree here. I'll add that this would mean we have WithOpenApi enabled by default in the templates.

[davidfowl]

@captainsafia We should write down what we think the template would look like after we finish the work (basically start with that end goal in mind). As well as a before and after simple todo API.

[nithinbandaru1]

So,

Does this mean

For Controller based APIs use?

builder.Services.AddEndpointsApiExplorer();

For Minimal APIs use?

builder.Services.WithOpenApi();

Also is this OpenApiDocument there? Does this mean Nswag, Swashbuck libraries doesn't need to construct OpenAPI doc from APIExplorer?

[captainsafia]

For Controller based APIs use?

Not quite. For controller-based APIs, you'll want to use AddApiExplorer. However, you'll rarely need to do this yourself since the ApiExplorer service is implicitly registered by by AddControllers (or AddMvc if you're using that).

builder.Services.WithOpenApi();

Something like this, but AddOpenApi to match the syntax of other DI-related APIs.

Also is this OpenApiDocument there?

Perhaps, or some type approximate to it. The main goal is to provide a way to capture the entire collection of OpenApiOperation descriptions in the app instead of a single one per endpoint.

[captainsafia]

Closing this.

We support generating the OpenAPI document by default now, and implicitly take a dependency on ApiExplorer so that we can generate docs for both minimal and controller-style APIs. Templates will be updated in .NET 9 Preview 5.