How Should I Apply OpenAPI/Swagger?

Introduction

Creating a good API is hard work. Especially if you do not follow a specific standard or best practice in creating an API.

It is quite hard to make it work. If you look at API Lifecycle Management, you will understand what I mean when you look at it in detail.

When I just started to learn about API development, It was similar to like the wild west.

Where there is not really a standard besides the basics like what is the type HTTP response status code you should use or the various HTTP request methods.

I believe it might a boring subject since there aren't many emphases on it. Unless you are talking about GraphQL which you will get tons of readers on it.

My mind was blown when I attended the API Days conference that was held in Singapore last year. When they had an API ecosystem map that talks about the various vendors.

API evangalist, offered insights into the tool and concepts about building a good API. I recommend spending some time to read it. As he is my goto resource if you want to know anything about the API development space.

What is OpenAPI?

OpenAPI is a set of open standards on how to design and document your API governed by the OpenAPI Initiative.

It consists of a group of industry experts to standardise and offer best practices on how an API should be created under the Linux Foundation.

It comes with its own tooling that was created by Smart Bear like the Swagger Eidtor. Smart Bear was involved in setting the foundation for OpenAPI. As they were the people who had created it in the first place, which they donated the API specification to the OpenAPI Initiative.

Which is explains why when you search for OpenAPI, the Swagger name will pop up in your search results. Since the previous name before it was donated and rebranded as OpenAPI.

Why OpenAPI?

The reason why do tons of companies & organisations adopts the OpenAPI specification. It is because it reduces on the amount of time and effort in dictating one's API due to it being an open standard.

So that any developer can consume and integrate into their products or service without worry.

Another reason is the tooling & ecosystem involved that makes it really easy to build an API. For anyone to design, develop, document, market & sell their API on the API marketplace like RapidAPI.

For me, when I am looking for API to integrate it for my development work. I will start by looking at their documentation.

I will try to find out if they are following the OpenAPI standard because it shows that they are serious in providing a good developer experience for their API.

Which in that area Stripe & Twillio sets a really high bar in that regard for their documentation & developer experience.

Creating OpenAPI Documentation

To follow the OpenAPI specification to document your APIs. I will go to the Swagger Editor and look through the OpenAPI version 3 specification to start writing my API documentation.

The good thing about the Swagger Editor is that it provides you with a pre-built template. Which you allows you to modify it to suit your needs without doing everything from scratch.

Another great thing about the editor is that it works like markdown editor. Which generates the OpenAPI documentation on the fly with syntax highlighting and error detection plus code generation in a programming language of your choice to use the API.

Conclusion

I had listed down the reasons why you should adopt OpenAPI specification. As part of your documentation and API standards within your API development lifecycle. Which is namely the ecosystem & tools surrounding the use of OpenAPI specification for API development?

By following an open standard, it allows API creator & developers to not worry about compatibility issues. When they are integrating the OpenAPI specification for API development.

This leads to mass adoption by companies and organisations to use the OpenAPI standard as part of their API development lifecycle.

Lastly, for you to get started, I would suggest you go to Swagger Eidtor to learn. By using OpenAPI from the templates that are provided by Smart Bear.

If you like this article sign up for my Adventurer's Newsletter for a weekly update in the area of Python, Startup and Web Development.

You can also follow me to get the latest update of my article on Dev
The original post was on How Should I Apply OpenAPI/Swagger? - Reading Time: 4 Mins
and cover image by tanialee gonzalez on Unsplash

Reference

• API Lifecycle Management
• HTTP response status code
• HTTP request methods
• GraphQL
• API Days
• Smart Bear
• OpenAPI Initiative
• Using OpenAPI to Build Smart APIs for Dumb Machines
• RapidAPI
• Stripe
• Twillio
• OpenAPI Version 3 Specification
• Deploying My Postman OpenAPI to AWS API Gateway
• API 101
• OpenAPI Specification
• Getting Started WIth OpenAPI 3.0
• Better API Design with OpenAPI
• Swagger Eidtor