Skip to main content

How to setup Swagger UI for ASP.Net Web API

-

Setup Swagger UI for ASP.NET Web API with Swashbuckle

Swashbuckle is an open source project for generating Swagger documents for Web APIs. Swagger is an advance technique to represent RESTfull Web API. Swagger is working with an Application. You can configure Swagger inside your Application. Its very easy to use and integrate inside your API's

Basic features to get going with Swashbuckle are

  • Install Swashbuckle
  • Overview of configuration code
  • How to use API Keys

Install Swashbuckle

Swashbuckle is an open source repository built for both asp.net and asp.net core

GitHub Repos:

NuGet Repos:

Don’t worry about downloading the github repo above, it is here just for your reference so you can take a look at the code or documentation if needed. One thing I really like about this library is how much control you have.

To get started simple add your NuGet Dependency like you normally would. Since we are working with asp.net Web API we are going to use the .NET Framework version.

In the Package Manager console enter the following command

Package-Install Swashbuckle

 

Configuration Code

You should now have a SwaggerConfig.cs file located in you App_Start folder. Since we are using Owin Configuration there is now a simple command that needs to be called SwaggerConfig.Register(config);. This will call the necessary configuration code that should be created for you.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
public class Startup 
{ 
    public void Configuration(IAppBuilder application) 
    { 
        var config = new HttpConfiguration(); 
        config.MapHttpAttributeRoutes(); 
        config.Routes.MapHttpRoute( 
            name: "DefaultApi", 
            routeTemplate: "v1/{controller}/{id}", 
            defaults: new { id = RouteParameter.Optional }); 
            
        // This is the call to our swashbuckle config that needs to be called 
        SwaggerConfig.Register(config); 
        
        // invoke the web API 
        application.UseWebApi(config); 
    } 
}

Swagger Config

The nice thing when you install the library is it puts a lot of the documentation in the code scaffolding so you don’t need to go hunting for it. By default the code scaffolding has most of the optional features commented out with docs right in the comments above each one and how it should be used.

You can choose to keep this verbose configuration file or shrink it down. I prefer to keep the verbose comments in because I find it useful for me or other devs on the team when we need to trun new features on for the swagger config. Our code snippet below is trimmed down for our purposes here, but the code sample attached is not.

1
2
3
4
5
6
7
8
9
public class SwaggerConfig 
{
    public static void Register(HttpConfiguration config) 
    { 
        config 
            .EnableSwagger() 
            .EnableSwaggerUi(); 
    } 
}

Both EnableSwagger and EnableSwaggerUi take configuration options which is where you will see all the documentation provided. To get the barebones install running you just need to call the 2 commands above.

API Keys

A common configuration with swagger is enabling API Keys to handle authorization to the API. When you are using a tool such as Postman you may include an API Key in the header. We have this same control with Swagger. There is a input control at the top of the page asking for an API Key. The user just plugs in their key and hits the Explore button. Now when they try to use any of the APIs the API Key is sent in the header and the page is once again usable.

How do you configure this? Going back to our configuration file SwaggerConfig.cs you need to specify the API Key in both methods EnableSwagger and EnableSwaggerUi

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
public class SwaggerConfig 
{ 
    public static void Register(HttpConfiguration config) 
    { 
        config 
        .EnableSwagger(c => 
        { 
            c.ApiKey("apiKey") 
                .Description("API Key for accessing secure APIs") 
                .Name("Api-Key") 
                .In("header"); 
        }) 
        .EnableSwaggerUi(c => 
        { 
            c.EnableApiKeySupport("Api-Key", "header"); 
        });
    } 
}

The most important parameters are the Name() and In() where the API Key name is specified in Name and In() determines where to place the API Key. In our example here we want this place in the header and we want it to be called “API-Key”.

After we specify the ApiKey in the first configuration section we need to tell SwaggerUi to enable the API Key which we again specify the Name and In parameters again.

At this point if you reload your swagger UI you will be able to specify your API Key and call your Web API through the Web Utility

Access Swagger UI from Browser

We have gone over the basics of setting up swagger UI but did not go over how to access our new API that is apart of our page.

 

Comments

Post a Comment

Popular posts from this blog

Email Sending through O365 using OAuth Protocol

-
  Microsoft Office365 EWS servers have been extended to support authorization via the industry-standard OAuth 2.0 protocol. Using OAUTH protocol, user can do authentication by Microsoft Web OAuth instead of inputting user and password directly in application Microsoft / Office 365 OAuth + EWS We can use the OAuth authentication service provided by Azure Active Directory to enable our application to connect with IMAP, POP or SMTP protocols to access Exchange Online in Office 365. To use OAuth with our application we need to register application on Azure Active directory and other steps also we need to do to get the access token back. Below are the steps   To use Microsoft/Office365 OAUTH in your application, you must create an application in  https://portal.azure.com . Sign into the Azure portal using either a work or school account or a personal Microsoft account. If your account gives you access to more than one tenant, select your account in the top ...
Read more

IoT Technology

-
Image
IoT technology The Internet of Things (IoT) is a system of interrelated computing devices, mechanical and digital machines.  IoT is a network of sensors where data is exchanged, using different connectivity protocols, with systems. This set up can be leveraged to create a new business application or to enhance an existing process. The exchange of the data can be bi-directional between sensors and systems Examples of sensors can be temperature sensors, motion sensors, flow meters, heart meter monitors, biometric devices, smoke detectors, & etc Examples of connectivity can be wifi, radio, GPRS, GSM, LAN, WAN, & etc. Examples of systems can be a remote health monitoring applications, SCADA applications, etc Look at next slide about the complete flow of IoT process Examples A doctor in US would like to monitor the heart rate and ECG of a patient in Hyderabad. This is done with the patient having sensors attached to him that collect the ECG data and the hea...
Read more

What is reverse proxy?

-
Image
  What is a reverse proxy? A reverse proxy is a server that sits in front of web servers and forwards client (e.g. web browser) requests to those web servers. Reverse proxies are typically implemented to help increase  security ,  performance , and reliability . In order to better understand how a reverse proxy works and the benefits it can provide, let’s first define what a proxy server is. What’s a proxy server? A forward proxy, often called a proxy, proxy server, or web proxy, is a server that sits in front of a group of client machines. When those computers make requests to sites and services on the Internet, the proxy server intercepts those requests and then communicates with web servers on behalf of those clients, like a middleman. For example, let’s name 3 computers involved in a typical forward proxy communication: A: This is a user’s home computer B: This is a forward proxy server C: This is a website’s origin server (where the website data is stored) In a stand...
Read more