Azure App Service API - Configure Swashbuckle

Introduction

If you are from a development background, you might have worked on Web Services or APIs  multiple times, either for your own consumption or for somebody else's. Each time you create an API, the consumer (either you, your colleague, or some other external parties) needs to write code for consuming the API methods that you have written and expose that based on the API Contracts or Interfaces.

In order to consume, you need to provide them the knowledge about your API methods, its parameters, and the return types for each and every method that you expose. In short, below are the challenges that one should take care of while building the APIs.

• Develop the API methods with the required functionality
• Provide the detailed documentation of the following
  
  
• Method names
• Input parameters
• Output.
  
  
• Examples of how to invoke the methods
• Develop the API Client Code to consume the methods.

It would take a lot of time for us to generate all of the above, each time we develop the API. It would be very nice if there was a tool that does all the above automatically. Right? Yes, there are open source API Frameworks that could help us in doing all the above (and even more) automatically (or with very minimal configurations). One such popular framework is Swagger.

Swagger

Swagger is a powerful open source framework backed by a large ecosystem of tools that helps you design, build, document, and consume your RESTful APIs.

Ref http://swagger.io/

In this article, we will learn how to integrate "Swashbuckle", a NuGet package for .NET. "Swashbuckle" is an open source project that helps us integrate Swagger to our Web API project.

Once you create a Web API project, install the Swashbuckle NuGet package, as shown below.



That’s it. Executing the above NuGet command will configure the Swashbuckle project to our Web API Project.

Below are the functionalities that get created by the "Swashbuckle".

• A UI for testing the Web API functions automatically.
• Discovers all the Controllers and provides us the basic documentation details, like MethodName, input types, and output types.

Let’s see how to access and review the above features.

Navigate to the following URL.

http://<<base url of your Web API>>/Swagger.

Once you type this URL in your browser, you will see something, as shown below.


As shown above, the Controllers are automatically listed in the Swagger UI.

Click any of the Controllers to view the methods available in it. 


It automatically pulls all the API methods along with the HTTP methods, as shown in the above screen capture.

We can further drill down to view the details of the individual API Methods by clicking on the desired one.



The above features provide the following details.

1. Name of the API Method
2. Example Input
3. Response Content Type so that the we can configure the function that consumes this API Method.
4. We can also test it by clicking on the ‘Try it out!’ button.

Clicking on the "Try it out!" button will execute the API Method and display the response of the method.



It has provided the following details.

1. The JSON of the Response Body
2. Response Code. In this example, it is 200 which means the call has been successful.
3. Response Headers

Summary

In this article, we have learned the following.

• What the Swagger is.
• What  Swashbuckle is - The Swagger component from NuGet for ASP.NET Web API.
• How to install Swashbuckle
• How to navigate to the Swashbuckle UI and explore a few of the basic features.

I hope you enjoyed reading the article. Your feedback is appreciated.