How is it going!! Welcome to scaleyourapp.com
This article is a comprehensive write-up on Swagger, a comprehensive suite of tools for building REST APIs. What is Swagger? Why do you need it when writing your REST-based APIs? What is OpenAPI? How is Swagger & OpenAPI related? What are the differences between them, If any? Is there any specification or any global standards for writing REST APIs?
This write-up will answer all your queries on it. So, without any further ado!!
Let’s get on with it.
1. What is Swagger?
Swagger is a set of open source tools for writing REST-based APIs. It simplifies the process of writing APIs by notches, specifying the standards & providing the tools required to write beautiful, safe, performant & scalable APIs.
In today’s software realm, there are no systems running online without exposing an API. We have moved from monolithic systems to microservices. And the whole design of microservices is laid on REST APIs.
Business can’t afford any loopholes or glitches in the functionality of the APIs after all the entire business rests on them.
Alright!! Enough. I get it how much APIs are important. But how does Swagger fit in here?
1.1 How does Swagger Help in Writing APIs?
When writing APIs from scratch, first thing as a developer which pops up in our minds is.
Am I doing things, right? I mean have I included the versioning system in the API. Are all the safety & data quarantine checks in place? How about the design? Seems Ok to me. Am I handling the errors correctly or am I missing something?
How helpful it would have been had there been a global specification for writing APIs.
I would just base my design on that & would be carefree.
When I had to write an API from scratch. Well, like there were so many things to get straight, I would go through different articles online. Go through docs of APIs exposed by Twitter, Facebook & stuff. Try to get an idea into the standards they were complying to. Hell, It was a time-consuming process.
Here is where swagger fits in. As I’ve stated before, it standardizes the whole process of writing APIs. Helps us figure things out which should ideally be spotted in the initial phases of writing software, help us weed them out, saving tons of time of code refactorization.
Let’s look into some of the superpowers of Swagger.
1.1.1 Be Accurate About Your APIs At the First Time
We know this already, in the first iteration of code design, things are never perfect. We have to keep tweaking stuff to make things aligned with our expectations. It’s really time-consuming running iterations tinkering with APIs over & over.
Swagger offers a tool called the Swagger Editor which helps us design our APIs based on the OpenAPI specification.
OpenAPI Woah!! Seems like we have a standard. Hurray!!
What is Swagger Editor?
Swagger Editor is a tool that helps us validate our API design in real time, it checks the design against the OAS Open API Specification & provides visual feedback on the fly.
The editor tool can be run anywhere, either locally or on the web. Provides instant feedback on the API design, points out if the errors are not handled correctly or if there are any issues with the syntax.
It also has intelligent autocompletion features, which enable us to write code faster. It is easy to configure & also enables the devs to create server stubs for the API for faster development.
With tools like Swagger Editor developers have an insight in real time on how the API design is coming along. By getting instant response from the stubs. It also helps us analyze how a third party developer would interact with the API.
My Industry Development Experience with Swagger
Back in the day, when I was writing a Search API for an e-commerce project from scratch. The task of the API was to return product search results against the queries fed to it.
We integrated Swagger with our Spring Boot REST based project to visualize the results fetched. Swagger UI helped us test the API for accurate results & errors when tested with several different crazy parameters.
Well the API response could also be received in the traditional browser tab, but where the Swagger really stood out was:
1. Testing the API. Also, it’s really comforting for devs to view their code, work on the UI. It was a bit easy to comprehend stuff, especially when I returned to the project after a bit of a break. Triggering commands from the Swagger UI was always easy or more comprehensible.
2. Swagger UI helped business people, like my product owner, get an insight into the functionality of the system, as it was developed over time. Obviously, you can’t always expect a business person to setup code in his system or check the API response in the browser by running the code locally. I would always ping him the swagger UI url & he could easily feed in the parameters in the UI & have a look at the response the system was returning. Much easier & simpler I would say.
1.1.2 Having A Standard API Design Across Different Teams
Swagger is to APIs what a Framework is to writing software.
Just like a framework helps standardize the software development process. Swagger provides global standards via OpenAPI, enabling a certain universal structure to the APIs.
Different people have different styles of writing software & if it weren’t for frameworks & standards. Maintaining software written by any other developer would be much worse than a nightmare.
Swagger specifies standards of common behaviour, patterns & a RESTful interface to the APIs. Different microservices teams in an organization don’t have to break their head comprehending, consuming & modifying foreign APIs.
Swagger offers a tool Swagger Hub which has an in-built API standardization tool which makes your code abide by the organizational design guidelines.
With this, it doesn’t matter if you have a team of 3 or 300. Things are always simple.
What is SwaggerHub?
SwaggerHub is a design & documentation platform for designing APIs with Open API.
It facilitates management within different teams & projects by creating folders with different APIs & permission levels for better organization. Stuff can be shared with authorized business management & stakeholders. It helps developers work together with stakeholders, incorporate new changes, get changes reviewed, merge stuff. Be in continual communication & track issues.
SwaggerHub offers common design models which can be saved in dedicated stores called domains & can be referenced & reused across the code. When writing backend code our APIs interact with several other services on the backend. Instead of firing up instances of those, SwaggerHub enables us to mock those APIs facilitating faster development.
1.1.2 Features Assisting API Development
While writing APIs there are so many things to get straight like handling errors properly, modularity of code, abiding by protocols & stuff. Swagger provides us with tools to quickly code our APIs taking care of all these things. Using swagger is taking the fastest road to prototype an API & then to a production deployable code.
Swagger’s open source tool CodeGen generates the boilerplate code when writing the API. Enabling the developer focus on the business logic as opposed to investing time in writing the syntactical stuff.
CodeGen takes care of the obvious plumbing & boilerplate code. Just like a Spring Boot project does to a Spring-based application.
1.1.3 Creating API Documentation
After being done with writing code. Another colossal, tedious task for developers is writing documentation for their code. My head hurts when I think about it.
Swagger lets us off the hook by generating & maintaining API docs for us. Saves a ton of time!! Also, we don’t have to go back & change the documentation every time the code changes.
All the docs are automagically updated by Swagger. We can also generate different versions of the API as per our requirements & whim. We can also configure Swagger to generate documentation for the existing APIs.
1.1.4 API Testing with Swagger
So, Guys!! Now our API is ready. Let’s move on to testing.
OpenAPI Spec helps us perform the functional, performance & security testing of our API. The ReadyAPI platform helps run API tests progressively.
With Swagger inspector, developers can inspect the API request & response to ensure they work as expected. The tool also helps in regression testing after major code changes.
Swagger has features enabling automatic API testing, mocking APIs, generating load tests. Stress testing of the API. Simulating corner cases such as peak traffic conditions, interacting with foreign data.
1.1.5 Monitoring API in Production
Once the code is deployed in production it has to be monitored for consistent behaviour. With Swagger, we can monitor our APIs in production for availability, speed & functionality.
It helps us track the API behaviour ensuring smooth execution & generates an alert if it spots anything amiss. With the Swagger API, we can programmatically manage the API monitoring process.
Write from the beginning of this article. I’ve been bringing up this term OpenAPI. What is it? Let’s dig in.
2. What is OpenAPI?
OpenAPI is the global standard for writing RESTful APIs. It like a specification which enables developers around the planet to standardize the design of their APIs. Also, comply with all the safety, versioning, error handling & other best practices when writing REST APIs from the ground up. And not just ground up, even existing APIs can be tweaked to comply with a global standard.
Besides, isn’t this pretty obvious, why complying to universal standards in the development of a product is helpful?
Initially, the OpenAPI was known as the Swagger specification. Swagger came up with the best practices of building APIs & then those best practices became the OpenAPI specification.
Tools like SwaggerHub helps the developers build APIs in browser-based editor complying to standards & having complete control over the design process.
With tools like Swagger Inspector, we can also generate our own API specifications & pass them around to other teams in the organization.
So, every time a new version of the API is created. SwaggerHub validates the API against the OpenAPI standards & lists out any major deviations from that. This way the inconsistencies in the design are detected & fixed early.
3. Is there Any Difference Between Swagger & the Open API?
OpenAPI is the specification & Swagger is the implementation of the specification. Just like, JPA is the specification & Hibernate is the implementation.
Swagger provides the tools for implementing the OpenAPI specification. Today OpenAPI is adopted by the big guns in the industry, contributing to it at the same time, evolving the API development process.
4. What is the difference between Postman & Swagger?
Postman is also an API testing solution just like Swagger. It started as a chrome app & now offers pretty much majority of the features required to develop & test APIs.
It’s been a while I’ve used Postman. Did use it a couple of years back when I was integrating the Facebook login with Spring social in an e-commerce project.
Swagger, on the other hand, is a suite of open source & commercial tools. It created the OpenAPI specification. So, this, in my opinion, is the primary difference. The specification part.
Besides, if you want to dig more into it. I guess you have to use both the tools, play around a bit & see what works for you.
All I am writing here is my experience with both the tools. I used Postman to test my APIs. I used swagger to have a browser-based UI, check the request & response. Show them to the business people, let them play around with it & get the feedback on how things should be.
5. More On the Blog
Well, Guys!! This was pretty much it. If you liked the article, do lemme know in the comments.
Share it with your geek friends.
See you in the next article.
- Distributed Systems, Scalability & System Design #1 – Heroku Client Rate Throttling
- Zero to Software/Application Architect – Learning Track
- Java Full Stack Developer – The Complete Roadmap – Part 2 – Let’s Talk
- Java Full Stack Developer – The Complete Roadmap – Part 1 – Let’s Talk
- Best Handpicked Resources To Learn Software Architecture, Distributed Systems & System Design