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!!