Swagger now a days is very popular. Many of us may already be using it. This blog is to articulate some basic information that can help you to understand WHAT, WHY and HOW questions about swagger.

OK! So, what is Swagger ?

Some of you might already have worked on SOAP web services (e.g. WCF). In web services world, there is a Web Service Description Language (WSDL) document which is used to publish information about:

• Supported Services and operations
• Input Parameters / Data Types
• Protocol, Security, Authentication, requirements for calling that API, etc.

The WSDL format is a standard and it is adopted by various frameworks which support creating SOAP services.

The Open API initiative was started by some experts in order to create, evolve and promote vendor neutral format of describing REST APIs. Swagger was donated to Open API Initiative. The terms Open API and Swagger are now interchangeably used.

In Short, Swagger standardizes the way a REST API should be described, no matter which technology you have used to create that REST API.

Swagger: Building Blocks

Swagger broadly can be divided into 3 different building blocks:

Middleware

This part has responsibility to generate the Swagger.json.
This part would iterate through all your API Endpoints and then it will generate a description document “swagger.json”.

It also has responsibility to expose the Swagger.JSON so that it can be used by Swagger UI.

You have to register a Middleware which can intercept and serve the Swagger page if swagger URL is triggered.

Swagger.json

Swagger.json is the way of describing your REST API. Swagger.json document is a special JSON document which describes:

• Metadata of the document
  • Who published API
  • Version of API, etc.
• The API Endpoints
• The Input Parameter Types for each API Endpoint
• Security Descriptions, etc.

If you are interested have a look at this repository of Open API Specifications to understand internals.

Swagger UI

This part takes swagger.json and renders it on the HTML. It also provides ability to call the REST API.

You don’t need to keep these HTML pages in your source code. Mostly the middleware intercepts the HTTP requests and serves the HTML Pages whenever swagger URL is

Hmm ! So how would it help me ?

The swagger can help you in at least two ways:

• Quick documentation of REST API Contract
• Hassle free integration with other applications using your APIs

The swagger documents all requirements required to call your REST API automatically. It shows all the exposed REST APIs and all the required data types.

All this information from swagger helps to ease the integration with other applications. All required information to call your APIs are easily accessible to them using swagger page.

Using Swagger

As I mentioned earlier, the Open API initiative was created to provide uniform way of documenting / describing the REST APIs – regardless of which framework you are using.

Swagger can be used using spring boot, you can find the example at this blog.

Swagger can be used in Asp .Net Core web APIs. There are two nuget packages that can be used

• Swashbuckle.AspNetCore
• NSwag.AspNetCore

I hope you enjoyed reading this article. If you want to know about any specific areas related to REST APIs, please comment and let me know. I would be happy to explain my thoughts in my blog articles.