In this article, we are going to learn how to integrate Swagger UI in an ASP.NET Core Web API application. 

The source code for this article is provided on our GitHub repository.

We have divided this article into the following sections:

The Need for Documenting our API

Developers who consume our API might be trying to solve important business problems with it. Hence it is very important for them to understand how to use our API effectively. This is where API documentation comes into the picture.

The API documentation is the process of giving instructions about how to effectively use and integrate an API. Hence it can be thought of as a concise reference manual containing all the information required to work with the API, with details about the functions, classes, return types, arguments and more, supported by tutorials and examples.

So having proper documentation for our API enables the consumers to integrate our APIs as quickly as possible and move forward with their development. Furthermore, this also helps them to understand the value and usage of our API, improve the chances for our API adoption and make our APIs easier to maintain and support.

Swagger/Open API

Swagger is a language-agnostic specification for describing REST APIs. The Swagger is also referred to as OpenAPI. It allows us to understand the capabilities of a service without looking at the actual implementation code. 

Swagger minimizes the amount of work needed while integrating an API. Similarly, it also helps API developers to document their APIs quickly and accurately.

Swagger Specification

Swagger Specification is an important part of the Swagger flow. By default, a document named swagger.json is generated by the Swagger tool which is based on our API. It describes the capabilities of our API and how to access it via HTTP.

Swagger UI

Swagger UI offers a web-based UI that provides information about the service. This is built using the Swagger Specification and embedded inside the Swashbuckle package and hence it can be hosted in our ASP.NET Core app using middlewares.

Integrating Swagger UI into our Applications

We can use the Swashbuckle package to easily integrate Swagger into our .NET Core Web API projects. It will generate the Swagger specification for our project. Additionally, the Swagger UI is also contained within Swashbuckle.

There are three main components in the Swashbuckle package:

Swashbuckle.AspNetCore.Swagger: This contains the Swagger object model and the middleware to expose SwaggerDocument objects as JSON.

Swashbuckle.AspNetCore.SwaggerGen: A Swagger generator that builds SwaggerDocument objects directly from our routes, controllers, and models. 

Swashbuckle.AspNetCore.SwaggerUI: An embedded version of the Swagger UI tool. It interprets Swagger JSON to build a rich, customizable experience for describing the web API functionality.

Installing the Package

The first step is to install the Swashbuckle package.

We can execute the following command in the Package Manager Console window:

Install-Package Swashbuckle.AspNetCore -version 5.0.0-rc4

This will install the Swashbuckle package in our application.

Configuring the Swagger Middleware

The next step is to configure the Swagger Middleware.

Let’s make the following changes in the ConfigureServices() method of the Startup.cs class:

This adds the Swagger generator to the services collection.

In the Configure() method, let’s enable the middleware for serving the generated JSON document and the Swagger UI:

By executing these steps, The Swagger is configured and ready to use in our project.

Exploring the Swagger UI

First, we are going to create an Employee class:

Then, let’s create an API controller with action methods. We are going to use some mock data and keep the focus on understanding Swagger’s capabilities:

Now, let’s run the app and navigate to https://localhost:<port>/swagger/v1/swagger.json. We can see that a document describing the endpoints is generated:

swagger-json

The Swagger UI can be found at http://localhost:<port>/swagger:

swagger-ui

Now we can explore the API via the Swagger UI and it will be easier to incorporate it into other applications.

We can see each controller and its action methods listed here.

Once we click on an action method, we can see detailed information like parameters, response, and example values. There is also an option to try out each of those action methods:

swagger-ui-action-method

By clicking on the Try it out button, we can test the endpoint and see the response:

swagger-ui-try-it-out

In this section, we’ve explored the Swagger UI in detail. Now we’re going to look at options for extending and customizing it.

Extending and Customizing 

Swagger provides options for extending the documentation and customizing the UI.

Extending the documentation

Let’s look at the various options to extend the documentation.

API Info & Description

First, let’s see how we can specify the API info and description.

The configuration action passed to the AddSwaggerGen() method adds information such as Contact, License, and Description. Let’s provide some values for those: 

Now let’s run the application once again and explore the Swagger UI:

swagger-ui-api-info

We can see that the Swagger document is now updated with API Info.

XML Comments

For enabling XML comments, we need to do the following steps:

  1. In the Build tab of the project properties, check the box labeled XML documentation file. Let’s keep the auto-generated file path.
  2. Suppress warning 1591, which will now give warnings about any method, class, or field that doesn’t have triple-slash comments.

generate-xml-documentation-setting

In the ConfigureServices() method, configure Swagger to use the XML file that’s generated in the above step:

Now, adding triple-slash comments to the action method enhances the Swagger UI by adding a description to the section header.

Let’s add a summary:

This displays the summary against the action method:

action-method-with-summary

We can additionally add <remarks> element to the documentation. It supplements information specified in the <summary> element and provides a more robust Swagger UI. The <remarks> element content can consist of text, JSON, or XML:

This will enhance the UI with additional info:

action-method-with-summary-and-remarks

We have looked at how to enhance the documentation using XML comments.

Using Data Annotations

We can decorate a model with attributes to enhance the documentation.

Let’s add a [Required] attribute to the EmailId field of the Employee model:

This gets reflected in the Swagger UI:

required-attribute-in-swagger-ui

Describing Response Types

The developers who consume our APIs are usually more interested in what it returns- specifically the response types and error codes. Hence it is very important to describe our response types.  These are denoted using XML comments & data annotations.

Let’s enhance the response types a little bit:

This will reflect in the Responses section:

repsonse-types

In this section, we’ve looked at various options for extending the documentation.

Customizing the UI

The default UI of Swagger is pretty good. But we can customize it If we wish to do so. We may change the documentation pages to represent our brand or theme. Branding the Swagger components requires adding the resources to serve static files and building the folder structure to host those files.

First of all, we are going to enable static file middleware in the Configure() method in Startup.cs file:

After that, let’s acquire the contents of the dist folder from the Swagger UI GitHub repository. This folder contains the necessary assets for the Swagger UI page.

Let’s create a wwwroot/swagger/ui folder, and copy the contents of the dist folder into it.

Additionally, let’s create a custom.css file in wwwroot/swagger/ui with the following CSS to customize the page header:

We have to reference custom.css in the index.html file inside ui folder, after any other CSS files:

Finally, let’s browse to the index.html page at https://localhost:<port>/swagger/ui/index.html, enter https://localhost:<port>/swagger/v1/swagger.json in the header’s textbox, and click the Explore button. 

We can see that the UI is now customized with the changes we made:

customized-ui

In this section, we have looked at options for customizing the Swagger UI.

Conclusion

We have looked at the following topics in this article:

  • The need for documenting our APIs
  • Swagger/Open API – Swagger Specification & Swagger UI
  • Integrating Swagger UI into an ASP.NET Core Web API
  • Extending the Swagger Documentation
  • Customizing the Swagger UI

If you have enjoyed reading this article and if you would like to receive the notifications about the freshly published .NET Core content we encourage you to subscribe to our blog.