Microsoft released ASP.NET Core 5. One of the new features mentioned in the ASP.NET Core 5 announcement is the "built-in" support for OpenAPI and Swagger UI in ASP.NET Core 5 Web API's. This isn't so much a new built-in feature as it is a change in the ASP.NET Core 5 Web API Project Template. Microsoft is simply including Swashbuckle as part of the template and configuring it with some default settings for your project.


If you edit the project file of a new ASP.NET Core 5 Web API, you will notice the inclusion of the Swashbuckle.AspNetCore package.

  <PackageReference Include="Swashbuckle.AspNetCore" Version="5.5.1" />


In the ConfigureServices method in the Startup.cs file you will notice the configuration to create an OpenAPI Specifications Document. Swagger UI uses this document to populate a user interface that allows one to explore and test the ASP.NET Core Web API.

services.AddSwaggerGen(c =>
    c.SwaggerDoc("v1", new OpenApiInfo { Title = "WebApi", Version = "v1" });

In the Configure method in the Startup.cs file you will see Swagger being added to the middleware pipeline.

app.UseSwaggerUI(c => c.SwaggerEndpoint("/swagger/v1/swagger.json", "WebApi v1"));

Debug Launch Settings

And last, you will notice that the debug launch settings have been set to open a browser to "swagger" to display the Swagger UI when the project is run.

Therefore, when you create a new ASP.NET Core 5 Web API and immediately run the project, the browser will open up to the Swagger UI, allowing you to explore and test the API.

ASP.NET Core 5 Web API OpenAPI and Swagger UI

Azure API Management

The reason Microsoft added OpenAPI support to the template is for this new feature in Visual Studio 2019 for Azure API Management. From the announcement:

"When ASP.NET Core API projects enable OpenAPI, the Visual Studio 2019 version 16.8 and later publishing automatically offer an additional step in the publishing flow. Developers who use Azure API Management have an opportunity to automatically import the APIs into Azure API Management during the publish flow"

Going Further

If you're new to OpenAPI, Swagger UI, and Swashbuckle, there's a lot more that can be done to document ASP.NET Core Web API's. You will want to add proper XML Documentation to your code for sure, which will allow you to add more information to the generated OpenAPI Specifications Document and Swagger UI. You will also want to lock down and correct which media types your API consumes and produces as well as which status codes it returns. Lots of cool stuff I wish they would have included with the sample ASP.NET Core 5 Web API Project Template to make it a little more real-world.