In this article, we are going to learn about the AddEndpointsApiExplorer method in ASP.NET Core. We will learn why we need it and how we use it in our applications.
For this article, we will use an ASP.NET Core Web API application with Swagger support. If you feel the need to brush up, we have an introductory article about setting up Swagger.
Let’s begin.
What is AddEndpointsApiExplorer Method?
The AddEndpointsApiExplorer() is an extension method in the Microsoft.AspNetCore.Mvc.ApiExplorer package that comes bootstrapped with the Web API.
When setting up a Web API in Visual Studio, the AddEndpointsApiExplorer() method comes as part of the boilerplate code in the Program.cs file.
The method call builder.Services.AddEndpointsApiExplorer() registers services that expose information about our endpoints:
public static IServiceCollection AddEndpointsApiExplorer(this IServiceCollection services)
{
// Try to add default services in case MVC services aren't added.
services.TryAddSingleton<IActionDescriptorCollectionProvider, DefaultActionDescriptorCollectionProvider>();
services.TryAddSingleton<IApiDescriptionGroupCollectionProvider, ApiDescriptionGroupCollectionProvider>();
services.TryAddEnumerable(
ServiceDescriptor.Transient<IApiDescriptionProvider, EndpointMetadataApiDescriptionProvider>());
return services;
}
These services are used by Swagger and any other API documentation tool to generate documentation for our API in order for it to know underlying information.
The vital information we get in the documentation includes endpoint URLs, HTTP methods, request parameters, and schemas for our requests and responses.
Having set a foundation on what the method is and what it does, let’s pass to action.
Why Do We Need AddEndpointsApiExplorer Method?
Let’s set up a new ASP.NET Core Web API project in Visual Studio with Open API support enabled. Alternatively, we could use the command line by running the command:
dotnet new webapi -n SampleApi
After that, let’s add a Minimal API endpoint to the Program.cs file:
app.MapGet("/car-models", () => new[] { "Chevrolet", "Tesla", "Nissan" });
For learning purposes and to understand the effect of the AddEndpointsApiExplorer() method, let’s go ahead and delete it from Program.cs. When we run our application, we only see the /WeatherForecast endpoint in the Swagger UI documentation.
Internally, Swagger uses types registered by the AddEndpointsApiExplorer() method to generate API documentation. It goes without saying, that when we remove the method call, these necessary services aren’t registered. That’s why the MapGet endpoint is missing in Swagger UI.
On the other hand, the controller endpoint is displayed because the AddControllers() method calls AddApiExplorer() which only registers services to discover controller endpoints and not Minimal API endpoints. If you want to learn more about AddApiExplorer() check out this Introduction to ApiExplorer by Andrew Lock.
Now, let’s add back the AddEndpointsApiExplorer() method call to the Program.cs file. At this point, if we run the API we get a Swagger UI with the two endpoints:
- The
/WeatherForecastendpoint - The
/car-modelsendpoint
The AddEndpointsApiExplorer() was created specifically to make Swagger support Minimal APIs. Even though we also have the method in a Web API application with controllers, removing it from the application does not break it.
However, if we remove both AddControllers() and AddEndpointsApiExplorer() calls from our service registration, we get an error running the application. This is because after removing the method calls, registration of services required by Swagger does not happen. So when Swagger tries generating the API documentation, it fails. This explains why we need to call both methods in our application when we have both Controller APIs and Minimal APIs.
Conclusion
In this article, we have learned about the AddEndpointsApiExplorer method in ASP.NET Core and its role in generating API documentation. In addition to that, we have covered how it differs from AddApiExplorer called by AddControllers. You can build on this knowledge in your applications going forward. Until next time, keep learning!
