Swagger

What is Swagger?

In this series of blog posts, we will try to explain what is swagger and how can we use it  for doing the API Documentations as well how we can integrate the Swagger in Visual Studio MVC solutions, Swagger also help to debug your API without using any third party tool like PostMan.

Apart from this, swagger JSON also help to integrate your API in Azure API management.

Why Swagger?

Swagger is a framework for describing your API, Swagger help to provide the clear documentations.
It specifies the format (URL, method name, Type (POST, PUT..etc.)) Representation that to describe the API. Swagger provide the tool which generate the documentation during the development of Application code.

An application developer who is developing API, can describe the information of that API in the same section where is developing code. Swagger tool will read the code and add it in the documentation sections. It store all the information in XML.

  • Swagger is mainly useful for describing and consuming about API’s.
  • Understanding the various methods used in our Web API.
  • The data shows in JSON format.

 Integrating Swagger in Visual Studio Solutions.

Adding Swagger in VS 2017

    • Create MVC API Project
    • In the ‘Solution Explorer’window, right-click the ‘webDemo’ project and click ‘Manage nuget packet’ menu item.
    • In the ‘Nuget Package Manager’window, select ‘Browse’
    • In the textbox inside ‘Nuget Package Manager’window, type ‘SwashBuckle’.
    • In the left side of ‘Nuget Package Manager’window, select ‘SwashBuckle.Net45’ package
  • In the right side of the ‘Nuget Package Manager’window, click the ‘Install’
  • In the ‘Review Changes’window, click the ‘Ok’ button.
  • In the ‘License Acceptance’window, click ‘I Accept’
  • Close the ‘Nuget Package Manager’window

Configure the XML documentation. SwashBuckle will use the XML documentation to describe the WEB APIs actions.

    1. In Solution Explorer go to Project and click on ‘Properties’ menu items.
    2. Click on Build Tab, below ‘Output’, click ‘Xml Document File’ In the textbox at right you will see the path ‘bin\webDemo.xml’.

XML Documentations Parameter

  • Summary

///
/// To Give the Information’s of the API Functions
///

  • Remark

///
/// You can give detail information’s of the API
/// Also you can provided the input parameter example over here
///

Configure the SwashBuckle.

    • In Solution Explorer click on ‘cs’file
  • The ‘Register’method of the ‘SwaggerConfig’ class is configured to be executed as a ‘PreApplicationStartMethod’.
  • Include the following method inside ‘SwaggerConfig’class:


protected static string GetXmlCommentsPath()
{
return System.String.Format(@"{0}\bin\webDemo.XML",
System.AppDomain.CurrentDomain.BaseDirectory);
}

  • Uncomment the following block of code inside the “Register”method:

    c.IncludeXmlComments(GetXmlCommentsPath());

Configure the Server URL

By Default, the service root url always redirect i.e. localhost/api/swagger. You will be having different environment and for all the environment URL will be different.

Below are the configuration steps.
SwaggerConfig.cs file we need to add the below 2 line.

string myCustomBasePath = ConfigurationManager.AppSettings["ServerURL"].ToString();

c.RootUrl(req => myCustomBasePath);

  • In Web.Config you need the URL based on the Environment.

Configure the Swagger to use with Token.

Api authorization is done using the Token, while accessing the API through there is facility we can pass the Token.

  • Uncomment the ‘EnableApiKeySupport’ in EnableSwagger

c.ApiKey("apiKey")

.Description(“API Key Authentication”)

.Name(“apiKey”)

.In(“header”);

  • Uncomment the ‘EnableApiKeySupport’ EnableSwaggerUi

c.EnableApiKeySupport("Authorization", "header");

You can pass the bearer token, in the Textbox as mentioned in the screen below.

Integrating Swagger JSON in Azure API Managements.

In Azure API Management, Import Section you will get the screen From URL, with the Option “Swagger”, You Just need to add the URL http://localhost:51926//swagger/docs/v1, all your specification will get automatically load in Azure API Management.

Note: – This URL need to be public URL, which mean it should accessible over the internet.


Also in SwaggerConfig.cs file you need to uncomment the below Code.

c.SingleApiVersion("v1", "SCAPPS.Web.API");

References

https://www.red-gate.com/simple-talk/dotnet/net-development/visual-studio-2017-swagger-building-documenting-web-apis/

https://docs.microsoft.com/en-us/aspnet/core/tutorials/web-api-help-pages-using-swagger?tabs=visual-studio

Advertisement

Leave a Reply

Fill in your details below or click an icon to log in:

WordPress.com Logo

You are commenting using your WordPress.com account. Log Out /  Change )

Twitter picture

You are commenting using your Twitter account. Log Out /  Change )

Facebook photo

You are commenting using your Facebook account. Log Out /  Change )

Connecting to %s

This site uses Akismet to reduce spam. Learn how your comment data is processed.