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.

c.DescribeAllEnumsAsStrings();

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(); } 

Summary

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!