Integrate swagger with ASP.NET Core minimal APIs

In the previous part
of this article series we developed minimal APIs for performing CRUD operations
on the Employees table. Once you build the minimal APIs, you typically want to
test them by invoking their endpoints. The best way to do so is by building a
client application using HttpClient or JavaScript. However, creating such a
client can be time consuming. You might want to quickly test the minimal APIs
before moving ahead with your development. That's where
Swagger can be helpful. In this article we will
integrate Swagger support into the minimal APIs and test the CRUD operations.
Open the same MinimalAPI project you created in the previous part. Once the
project is loaded in Solution Explorer add the following NuGet packages to it
using Manage NuGet Packages dialog:

The Swashbuckle.AspNetCore package contains everything you need to integrate
Swagger into your minimal APIs.
Recollect the following figure from the previous part that shows a checkbox
"Enable OpenAPI support" during project creation. If you have kept the default
selection unchanged, Swashbuckle.AspNetCore is already added for you. Otherwise,
you need to add it manually as mentioned above.

Now open Program.cs and add the following code before the builder.Build()
call.
var contact = new OpenApiContact()
{
Name = "FirstName LastName",
Email = "user@example.com",
Url = new Uri("http://www.example.com")
};
var license = new OpenApiLicense()
{
Name = "My License",
Url = new Uri("http://www.example.com")
};
var info = new OpenApiInfo()
{
Version = "v1",
Title = "Swagger Demo Minimal API",
Description = "Swagger Demo Minimal API Description",
TermsOfService = new Uri("http://www.example.com"),
Contact = contact,
License = license
};
builder.Services.AddEndpointsApiExplorer();
builder.Services.AddSwaggerGen(o =>
{
o.SwaggerDoc("v1", info);
});
var app = builder.Build();
The above code creates three
Open API objects -
OpenApiContact, OpenApiLicense, and OpenApiInfo. The first two object wrap
information about Web API's contact person and license information. The
OpenApiInfo objects wraps these two objects. The AddSwaggerGen() call followed
by nested SwaggerDoc() call configures Swagger document generator by passing the
OpenApiInfo object.
Note that SwaggerDoc() method's first parameter indicates a name given to
this Swagger document. You can call SwaggerDoc() multiple times to specify
multiple Swagger documents. The name in this case is v1 but you can use any
string value. This name is also used while configuring the Swagger middleware as
discussed next.
Now add the following code just before app.Run() call.
app.UseSwagger();
app.UseSwaggerUI(c =>
{
c.SwaggerEndpoint("/swagger/v1/swagger.json",
"Swagger Demo Minimal API v1");
});
app.Run();
The above code first calls UseSwagger() method followed by UseSwaggerUI()
method. The SwaggerEndPoint() method configures the Swagger end point by
specifying two things - URL to swagger.json and name to display in the document
selector (this will be clear shortly).
So far so good.
Now run the application by pressing F5. This will result in the following
Swagger UI.

And at the bottom of the page you will have the APIs listed:

The details such as contact, license, and description are displayed on this
page. Below you can invoke the minimal APIs.
Now, expand the first GET minimal API and click on the Try it our button
followed by Execute button to invoke it.

You will see this JSON output returned by the API:

Next, invoke the GET by EmployeeID minimal API. Since it requires EmployeeID
parameter to be supplied the Swagger UI will display a textbox for entering its
value.

And here is the outcome:

To invoke the POST operation you need to supply a new Employee object (EmployeeID
can be 0 because it will be generated by the database) in JSON format as shown
below:

This time the response will be:

Notice that the response code is 201 and the newly created object is being
returned to the client along with location URL.
On the same lines execute PUT and DELETE operations (see below).

And

So far in this example our minimal APIs didn't require any authentication. In
the next article of this series we will implement JWT authentication to secure
our minimal APIs.
That's it for now! Keep coding!!