Working with Swagger

RESTful services have been popular for quite some time now. They are widely-used, primarily for improved performance, ease of use and maintenance. Swagger is a popular API for documenting your RESTful Web APIs. You need some way to document your RESTful services to know the endpoints and the different data models used in the request and response payloads. This article presents a discussion on how we can use Swagger to document our Web APIs easily.

What is Swagger? Why is it needed?

Swagger is a framework that can be used for describing and visualizing your RESTful APIs. Swagger provides a simple, yet powerful, way to represent your RESTful APIs so that the developers using those APIs can understand the endpoints and the request and response payloads in a much better way. The success of your API largely depends on proper documentation as proper documentation helps the developers understand ways to consume your API better. Here’s exactly where Swagger comes to the rescue.

Getting Started

Let’s now explore how we can add Swagger to our RESTful Web API project. Note that if you add Swagger to your Web API project, the default help pages are not replaced???both can reside side by side. First off, create a new Web API project in Visual Studio. Now, add Swagger to the Web API project using the following command at the NuGet Package Manager Console Window.

Install-package Swashbuckle 

Alternatively, you can search for Swashbuckle in NuGet Package Manager and install the package from there. Once Swashbuckle has been successfully installed, navigate to App_Start folder in the Solution Explorer Window and you would observe a file called SwaggerConfig.cs created there. This file contains all the necessary configuration details related to Swagger.

Here’s how the Register method of the SwaggerConfig class would look after changing the title appropriately. This is the minimum configuration needed to enable Swagger and the Swagger UI for your Web API project.

public static void Register()        {            GlobalConfiguration.Configuration                 .EnableSwagger(c =>                    {                        c.SingleApiVersion("v1", "Documentation for SampleWebAPI");                    })                .EnableSwaggerUi();        } 

Lastly, start your Web API project and navigate to http://localhost:[Port]/swagger where [Port] refers to the port number at which your Web API is hosted. That’s all that you would need to see your Web API methods documented using Swagger engine in the Swagger UI.

Customizing Swagger

You can add some more spice to the documentation generated by Swagger. As an example, you can customize your documentation to incorporate XML comments. To do this, you should enable XML documentation in the build process. Let’s explore how you can do this. Select the Web API project in the Solution Explorer Window, right-click and click on Properties. Click on the Build tab in the left pane, check the “XML documentation file” checkbox and specify the path for the generated XML documentation file.

Next, you should let Swagger know that XML comments should be incorporated in the Swagger metadata by specifying the following in the Register method of the SwaggerConfig class.

c.IncludeXmlComments(string.Format(@"{0} binSampleWebAPI.xml", System.AppDomain.CurrentDomain.BaseDirectory)); 

Here’s how the updated Register method would now look:

 public static void Register()        {            GlobalConfiguration.Configuration                 .EnableSwagger(c =>                    {                        c.SingleApiVersion("v1", "Documentation for SampleWebAPI");                        c.IncludeXmlComments(string.Format(@"{0}inSampleWebApi.xml", System.AppDomain.CurrentDomain.BaseDirectory));                    })                .EnableSwaggerUi();        } 

You should make sure that your controller methods and the models have XML comments in them so that you can see them using the Swagger UI. Once that’s in place, you would be able to see more details when the Swagger UI is running.

Want to customize even further? You can add the following line to the Register method in the SwaggerConfig class to ensure that the enum values are displayed as strings – for a better representation.


The updated Register method would look like this now:

public static void Register() {            GlobalConfiguration.Configuration                 .EnableSwagger(c =>                    {                        c.SingleApiVersion("v1", "Documentation for SampleWebAPI");                        c.DescribeAllEnumsAsStrings();                        c.IncludeXmlComments(string.Format(@"{0}inSampleWebApi.xml", System.AppDomain.CurrentDomain.BaseDirectory));                    })                .EnableSwaggerUi(); } 


Swagger provides a great way to easily document your RESTful services. You can add Swashbuckle easily to your Web API project and customize it as and when needed. This article presented an overview on how we can work with Swagger to document our RESTful Web API. Happy reading!

Share the Post:
Share on facebook
Share on twitter
Share on linkedin


The Latest

homes in the real estate industry

Exploring the Latest Tech Trends Impacting the Real Estate Industry

The real estate industry is changing thanks to the newest technological advancements. These new developments — from blockchain and AI to virtual reality and 3D printing — are poised to change how we buy and sell homes. Real estate brokers, buyers, sellers, wholesale real estate professionals, fix and flippers, and beyond may

man on floor with data

DevX Quick Guide to Data Ingestion

One of the biggest trends of the 21st century is the massive surge in internet usage. With major innovations such as smart technology, social media, and online shopping sites, the internet has become an essential part of everyday life for a large portion of the population. Due to this internet

payment via phone

7 Ways Technology Has Changed Traditional Payments

In today’s digital world, technology has changed how we make payments. From contactless cards to mobile wallets, it’s now easier to pay for goods and services without carrying cash or using a checkbook. This article will look at seven of the most significant ways technology has transformed traditional payment methods.