ASP.NET Web API 2 Documentation And Testing Using Swashbuckle/ Swagger

Many of us have been using ASP.NET Web API 2 (a popular framework for building RESTful APIs). I have being using that for a couple of years now, especially focused on REST APIs used for different clients such as ASP.NET MVC, JavaScript based UI framework like JQuery, AngularJs, KnockOut, etc, and handheld devices like mobiles, Tablets, etc.

 

One of the major time consuming tasks is to give proper documentation, unit testing it, and, most importantly, telling the other teams how the APIs are designed and documented.

 

We always had issues of other teams complaining about how to use these APIs, what are request and response types, how shall they form a JSON request or what is a JSON response? ASP.NET Web API 2 gives us documentation by including help pages; I had used that which actually solved my issues a bit but not to a great extent.

 

I was looking for a tool to minimize my team's efforts involved in interacting with other teams just to teach them how to use API.  I got Swagger; this is an excellent tool for solving my team's efforts.

 

Swashbuckle is a combination of ApiExplorer and Swagger/swagger-ui and provides a rich discovery, documentation and playground experience to your API consumers.

Some of the features you get with Swashbuckle are:

• Auto-generated Swagger 2.0
• Seamless integration of swagger-ui
• Reflection-based Schema generation for describing API types
• Extensibility hooks for customizing the generated Swagger doc
• Extensibility hooks for customizing the swagger-ui
• Out-of-the-box support for leveraging XML comments
• Support for describing ApiKey, Basic Auth and OAuth2 schemes ... including UI support for the Implicit OAuth2 flow

Create ASP.NET Web API 2

Create ASP.NET Web API 2 project using Visual Studio 2015 Community Edition targeting .NET 4.5 framework.

Note: It's not mandatory to use Visual Studio 2015 Community Edition

 

1. I am creating pure Web API project without MVC components loaded because intention is RESTful APIs don't need MVC.
2. No Authentication because its simple example.

Add models to new created Web API

I am building very simple API comprised of Books and Authors with their CRUD operations. So let's create two class files "Books" and "Authors" in "Models" folder of Web API project. Download Source Code from GitHub.
 
Add Web API controller class

 

Let's create BooksController and AuthorsControllers which acts our WEB API which are consumed by various clients.



The class diagram shows both API controllers have CRUD-related operations with GET having an overload method for getting data using ID. Source code is included so don't worry.

 

 Add proper comments to controller methods. This is an essential part for any API being built as it gives the right kind of direction to clients consuming this.

 

A poorly documented Web API is more difficult to use then develop it.

Adding SwashBuckle using Package Manager Console

Its time to add SwashBuckle with Swagger UI to our Web API, this can be done either "Manage NuGet  Packages" or "Package Manager Console".

 

Open "Package Manager Console" in your VS 2015 and run this command Install-Package Swashbuckle. This will install the necessary packages to our Web API project as shown below:



Enabling Swagger UI, XML documentation

One of the primary aims of this article is to show case documentation of Web APIs along with testing of Web API interactively.

 

The API controller classes have XML documentation written on all action methods, we need to generate XML file for Swagger to read them while running application.

 

Right click project properties, move to "Build" section and move to "Output" and enable "XML documentation file" as shown in image below.



Now that we have enabled XML documentation, it's time to configure Swagger to show UI, XML documents. When we installed SwashBuckle package from NuGet, it created "SwaggerConfig.cs" file in "App_Start,"  you can see this in the above image also.

SwaggerConfig.cs has following code to ensure what we need - XML documents, UI to testing API:

 

 Let me summarize the points from above image:

1. Provides version number, Name for API UI
2. Includes XML comments which we enable in above steps, its read from BIN folder 
3. Enables Swagger UI which we will see next

View the Web API in Swagger UI

 

Build project to ensure everything works fine, run the application to view browser, and navigate to this path "http://<yourAPIUrl>/swagger". 

Place "yourAPIUrl" accordingly, it might localhost with some port.

 

Here is the First look of Web API using Swagger UI, isn't it wonderful !!! It lists all controllers in our web Api project, we have "Books" and "Authors" controllers written.

 

It also lists controllers action method like GET, POST, PUT, DELETE along with documentation.

 

Now lets do Web API testing, this is even more powerful then XML features. Below image shows steps involved in POST a Book,



Most interesting part is POINT 2 shows sample JSON request type that needs to composed, clicking on that it fills POINT 3 box, so we don't need to worry about composing JSON request also. Click Point 5 to execute the API method and its response is shown below:

 

Point 1 here shows XML documentation from the source code, giving us a much clearer picture of what the parameter is all about.

 

Here the image of Authors API testing of GET,

 

How to use it this in daily project works

1. This is simple Web API without any authentication, no data access because it was meant to be simple. But overall clients consuming these Web APIs are not concerned about its internal implementation. So just give "http://<yourAPIUrl>/swagger" link after hosting on IIS.
   
   
2. Let clients consuming these API look into this Swagger UI which is well documented, testable with preformed request object.
   
   
3. Any new controllers added to Web API project just shows up in Swagger UI.

This really saves lots of time to coordinate with other teams/ clients who are consuming Web API. Download Source Code from GitHub.