Bonjour Swagger! says the Web Apps

[Source: ]

A huge revolution in the IT industry was the information-overload in recent decades due to the growth and usage of technology. This information overload is what’s know as “Big Data” and 70% of the information we have till date was generated during the last decade. The volume of the data, speed of generation, variety of the data, the value of it and the trustworthiness of the data is measured at very large scale, thus called as Big Data.

[Source: ]

Let’s start with API

As time progressed developers started to move from standalone applications to web-based applications. Nevertheless exposing the functionalities and data to the end-users with a huge load of data, while providing security and ensuring performance for better user-experience was never a piece of cake for the developers and the businesses. Web APIs (Application Programming Interface) came into the picture in the early 2000s to facilitate and abstract the pain away.

APIs are a set of definitions, protocols, and tools used to build frequently used functionalities in application software. For example, if an application wants to communicate with another application to accomplish a task both can simply use an API which acts as a predefined contract. So that a single application doesn’t have to implement all the functionalities it needs. It can simply pool resources and data from other applications and complete the intended tasks. This feature expanded the communication network and the opportunities to grow as a business.

[Source: ]

Over to Swagger

Different types of APIs are available to serve various requirements. SOAP (Simple Object Access Protocol) API and RESTful (Representational State Transfer) API are commonly used APIs. Just like we use WSDL (Web Service Definition Language) to create SOAP API definitions we have WADL (Web Application Description Language) to create REST API definitions. WSDL and WADL are XML-based documentation that gives the overall description of the web/network services, endpoint details, the methods that are used in the service and parameters passed.

The complexity of the APIs varies depending on the domain and the requirements. Therefore, designing, creating and maintaining them became a hectic task for the developers. Also, compared to XML, JSON is a lightweight and widely used format for data transfers. These factors made a huge impact in introducing Swagger to the API world.

Swagger, an introduction

Swagger is nothing but an open-source software framework consisting of a set of tools to maintain API life-cycle which includes the design, create, document and maintain phases. Swagger Editor, Swagger UI, Swagger Codegen, Swagger Parser, Swagger Core, Swagger Inspector, and SwaggerHub are the tools in Swagger. Out of these the following are the 3 commonly known and used components,

  1. Swagger Editor
  2. Swagger UI
  3. Swagger Codegen

Swagger Editor is used to design the API which has 2 sub-components in it. An editor to type the content and a viewer to visualize the changes made in the editor. The following image illustrates the Swagger Editor sub-components.

[Fig 1: The editor is placed in the left and the viewer is placed in the right]

Swagger UI is used to view the created swagger files in detailed view. Each method is displayed as a separate component with the parameters, response code, corresponding HTTP verb, path and API metadata.

[Fig 2: Swagger UI with openapi 3.0.0 file content]

Swagger Codegen is an open-source code-generator to build server stubs and client SDKs directly from a Swagger defined RESTful API.

[Fig 3: Generate server stubs and client SDKs(Software Development Kit) using Swagger Codegen component Source: ]

OpenAPI vs Swagger

In recent times we may have come across this dilemma between Swagger 3.0.0 and OpenAPI 3.0.0. Let’s take a look at these terms individually and analyze.

[Source: ]

is a specification on the REST APIs whereas is a set of tools to implement those specifications on the API life cycle.

In 2015, acquired Swagger and as a result, the specification was officially renamed from Swagger to OpenAPI. Both Swagger and OpenAPI allow the users to create specification in JSON and YAML formats.

Content Structure

Before SmartBear acquired Swagger, the specification docs were named as swaggerVersion 1.0, swaggerVersion 1.2, swagger 2.0. After the acquisition of Swagger, the specification docs are named as “openapi 3.0”. From swagger to openapi, not only the names but also the content structure got changed to make it more convenient to the users.

The basic difference between swagger 2.0 and openapi 3.0 version content structure is illustrated in the following image.

[Source: ]

Based on the above image certain components from swagger 2.0 have been combined into a single unit in openapi 3.0. They are,

  1. Servers = host + basepath + schemes
  2. Security = security + security definitions
  3. Paths = produces + consumes + paths
  4. Components = definitions + parameters + responses

Main components of OpenAPI

The most important components in the openapi 3.0.x version are,

  1. Swagger/OpenAPI version: mandatory field
  2. Info Object: mandatory field
  3. Paths field: Mandatory field
  4. Servers object: Optional field

Swagger/OpenAPI version

Any Swagger or OpenAPI file starts with swagger or openapi keywords to denote the version of swagger/openapi.

Info object

The info unit provides metadata of the specifications such as title, description, version of the file.

Paths object

The paths object provides the details of the HTTP methods used, URL paths, parameters, responses, response code.

Servers

“Servers” unit is one of the critical and new fields in openapi 3.0.x series, whereas other 3 fields are similar to swagger 2.0.

“Servers” is an array that provides the server API and base URL of an API. This piece of information was gathered in swagger 2.0 by combining host, basepath and schemes components. This wasn’t a convenient way as fetching data from 3 different components and combining them involved a significant amount of time and effort. Therefore, OpenAPI came with a single component called “servers” to provide all necessary details on the server API and base URL.

Since servers unit is not a mandatory field, the openapi 3.0.x file input can have different combinations. When integrating the swagger editor in a web application the developer must consider these concepts and make necessary validations to enhance the user experience.

The following are the cases identified related to servers.

Cases:

Case 1: Without servers field

[Fig 4: Swagger file without servers element]

Case 2: Servers field with an empty array

[Fig 5: Swagger file with an empty servers array]

Case 3: Servers field with complete URL

[Fig 6: Swagger file with complete URL in servers array]

Case 4: Servers field with variable mapping

[Fig 7: Swagger file with variable mapping in servers array]

Integrate Swagger Editor and Swagger UI to your Web App

Now that we have a basic understanding of API, Swagger and OpenAPI let’s get some practical experience in integrating the swagger editor and swagger UI in your web app. Let’s assume that you are developing a web app which has a feature to create APIs. So you prefer to use some tooling to enhance and enrich your application. To accomplish this, you have selected Swagger tools. Let’s see how we can achieve this.

The main requirements for this task would be a web app that you have created with a couple of basic UIs, swagger .js and .css files for both editor and UI and some basic javascript knowledge. The main reason for me to bring this topic in a blog post is because when I was searching on this topic I found it very hard to understand the concepts of swagger and find the necessary materials to implement this. So thought of making it as a blog post to help my friends out there who might have the same issues as I had.

I created a simple demo project to integrate the swagger editor and swagger UI into a web app and using that I can create, edit and view swagger files. Let’s take a look at the folder structure of my demo application.

[Fig 8: Project file structure]

Initially, I created an index page to route add, update and view pages. The swagger editor is placed inside add and update pages whereas the swagger UI is placed inside the view page.

[Fig 9: index.html]
[Fig 10: add.html]
[Fig 11: update.html]
[Fig 12: view.html]

The following js code was used to add the swagger editor and swagger UI in the corresponding pages.

swagger.js

In the above file, we are creating the swagger bundles by providing the DOM id of the element in which we wanted to embed the swagger tool, the layout type and the presets for the swagger editor and swagger UI respectively. Once the bundles are created we are placing them in the window (Browser’s window). By default, the swagger editor and swagger UI get the file content from the . Since I wanted to clear that content and provide a fresh editor and UI to the users, used editor.specActions.updateSpec(‘ ’); code to clear the content. The same result can be produced by inserting url: “http://httpbin.org/status/200" inside the swagger bundle.

This is the very basic and essential step you need to do to get the swagger editor and swagger UI in your web app. Just like calling any other js methods in an html page these methods were also invoked in the body tag’s onload method. The complete code for this project can be found in this . This can be applied to different technology-based web apps with slight modifications.

Summary

Let’s take a quick recap on what we have discussed so far in this blog post. The contribution of APIs to the Big Data era, API specifications, Swagger tools, the difference between Swagger and OpenAPI, the content structure of Swagger and OpenAPI files and integrating the swagger tools into a web app with a demo project. This blog is to give an overall idea about the above-stated topics so that it will be a quick start for the beginners and to get some confidence to work with those tools. The relevant resource links for the main topics are provided in the blog. I hope this was a useful read and made it easy for those who are seeking to understand REST API specifications. Happy learning and keep on practicing!!!

📝 Read this story later in .

👩‍💻 Wake up every Sunday morning to the week’s most noteworthy stories in Tech waiting in your inbox. .

--

--

--

Inquisitive | Senior Software Engineer @ WSO2

Love podcasts or audiobooks? Learn on the go with our new app.

Recommended from Medium

my Apps

Solving a Postgres Performance Mystery

How to Install OpenStack on Ubuntu with DevStack

Cognito User Pool Migration

Windows 11: The next Vista?

Getting Started With Git

The Limitations of Existing Deep Learning Frameworks: Resource Dependency

Comparing the Dask and Spark Interfaces

Get the Medium app

A button that says 'Download on the App Store', and if clicked it will lead you to the iOS App store
A button that says 'Get it on, Google Play', and if clicked it will lead you to the Google Play store
Saranki Magenthirarajah

Saranki Magenthirarajah

Inquisitive | Senior Software Engineer @ WSO2

More from Medium

REST API, Swagger, Postman, and REST API Playground

Mongo Aggregation Framework: A powerful feature

Node.js Architecture

Angular 11 + Firebase Cloud Messaging Push Notifications — Devstringx