Sep 16, 2019
Bonjour Swagger! says the Web Apps
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.
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.
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,
- Swagger Editor
- Swagger UI
- 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.
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.
Swagger Codegen is an open-source code-generator to build server stubs and client SDKs directly from a Swagger defined RESTful API.
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.
OpenAPI is a specification on the REST APIs whereas Swagger is a set of tools to implement those specifications on the API life cycle.
In 2015, SmartBear 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.
Based on the above image certain components from swagger 2.0 have been combined into a single unit in openapi 3.0. They are,
- Servers = host + basepath + schemes
- Security = security + security definitions
- Paths = produces + consumes + paths
- Components = definitions + parameters + responses
Main components of OpenAPI
The most important components in the openapi 3.0.x version are,
- Swagger/OpenAPI version: mandatory field
- Info Object: mandatory field
- Paths field: Mandatory field
- 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
Case 2: Servers field with an empty array
Case 3: Servers field with complete URL
Case 4: Servers field with variable mapping
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.
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.
The following js code was used to add the swagger editor and swagger UI in the corresponding pages.
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 pet store. 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 GitHub link. 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 Journal.
👩💻 Wake up every Sunday morning to the week’s most noteworthy stories in Tech waiting in your inbox. Read the Noteworthy in Tech newsletter.
