Enable Javascript

Please enable Javascript to view website properly

Looking for an Expert Development Team? Take two weeks Trial! Try Now

Implementing and Customizing Swagger UI in ASP.NET Web APIs

In this article, we shall see how to implement, customize Swagger in ASP.NET Web API.

Prerequisites

What is Swagger

Documentation always stands as an vital part with APIs designing. Swagger comes in as a documentation of RESTful APIs detailing its methods, parameters with datatype to be used along with output schema and headers information.

Swagger is representation of RESTful APIs endpoints. It helps developer consuming API, to understand methods definitions without actually looking into code written behind it. Consumers of APIs can visualize endpoints, helping in to better understanding of service and its methods.

In very simpler terms, Swagger helps in providing detailed specifications in a Visualize manner of RESTful Web APIs.

Building a basic ASP.NET RESTful Web API

Open Visual Studio (article is using Visual Studio 2017), create new ASP.NET Web project and give project a Name.

ASP.NET RESTful Web API

Select Web API as project template, and click Ok.

Web API as project template

This will create a basic ASP.NET Web API with controller name Values. This comes with built-in sample code for CRUD operations

ASP.NET Web API with controller

Build and Run the application, navigate to {localhost}/api/values Would display result as seen below, executing Get method of Value Controller.

Build and Run the application

Implementing Swagger

Open NuGet Package Manager. Right Click on Project ad select Manage NuGet Packages.

NuGet Package Manager

Click on tab ‘Browse’.

Type, ‘Swashbuckle’ in search box. Check ‘’Ínclude prerelease’ checkbox and press enter.

This will list project as shown in below image.

Select the one as shown , and click on Install.

click on Install

This will install all the required reference libraries required for Swashbuckle project.

Swashbuckle project

Go to Solution Explorer and check project folder App_Start.

A new file name SwaggerConfig.cs will be added to said folder. This confirms our successful installation of Swashbuckle project.

Solution Explorer

Build project and press Ctrl + F5 to launch the Web API.

And navigate to {localhost}/Swagger , this will open up Swagger UI,

{localhost}/swagger/UI/Index

This will list all the methods of Value controller as seen in below image.

launch the Web API

Click on any tab listed, and it open up with details like parameter expected to be enter, its Output schema along with a Try It Out button to test the endpoint. On clicking said button, it displays the desired output with Response Body and Response Code.

Response Body and Response Code

Same goes with other methods, with POST method,

POST method

With DELETE method,

DELETE method

With PUT method,

PUT method

In this article, we shall customize our Swagger UI with implementation of displaying Methods comments, added in code file.

It’s always recommended to enter comments for methods stating details about the endpoint. Details like what does that particular method or endpoint returns, any information about the parameter being passed and so on. Our objective is API should be understandable or readable for Consumers and Clients consuming API.

Question will arise, comments are made in code, then how it would be helpful for client. Answer is Swagger again. Yes, Swashbuckle a has a provision to display these comments, written in code, in to Swagger UI.

Add few Comments

For GET method, add few lines of code above method section. Also add few information regarding parameter id being passed, as shown in below image.

Comments

After adding comments, go to App_Start folder and open SwaggerConfig.cs file.

Go to line number 104 or search for keyword ‘IncludeXmlComments’

Once you are on said line, uncomment the code.

Visual Studio will prompt asking to create Method, ‘GetXmlCommentsPath()’ , follow the suggestion and create method, as seen in below images

App_Start folder

Method name ‘GetXmlCommentsPath()’ is created.

Method name

Go to Solution Explorer, Right Click on project and Click on Properties.

Now, click on Tab Name Build at left pane.

Under Output section, Check the box ‘ XML documentation file’ and copy the path being displayed.

At this path an XML document is being generated with all the comments added.

Solution Explorer

Return the newly added method in SwaggerConfig.cs, with copied XML location. Refer below image.

Return the newly added method

Again, build the project and launch application by clicking Ctrl + F5

Navigate to {localhost}/Swagger/

Comments are now displayed against the method.

launch application

Also, parameter details we added are now part of Swagger API

Swagger API

We can decorate the Title, specify the version number, can change the look n feel of Swagger API, can implement Javascript functions in UI and many similar customizations by tweaking code in SwaggerConfig.cs.

We saw how useful it is to have Web APIs with proper documentation. This not only make API readable for Client but also makes life easy for developers and Testers. Would recommend to try what you learned from this article. This goes with ASP.NET Web APIs. For implementing it with ASP.NET Core especially Core 2.0, implement with ASP.NET Development Services.

Recent Blogs

Categories

NSS Note

Some of our clients

team