How Should I Apply OpenAPI/Swagger?
Tags: opensource, webdev, beginners
Published: 2020-01-31 14:12:21

# 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][1], 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][2] you should use or the various [HTTP request methods][3].

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

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

[API evangalist][6], 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][7]. 

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][8] like the [Swagger Eidtor][9]. 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][10]. 

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][11] & [Twillio][12] 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][9] and look through the [OpenAPI version 3 specification][13] 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][9] 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](https://maxongzb.activehosted.com/f/1) 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
](https://www.maxongzb.com/how-should-i-apply-openapi-swagger-reading-time-4-mins/) and cover image by [tanialee gonzalez on Unsplash](https://unsplash.com/photos/Alm7tmPVmSU)

# Reference
* [API Lifecycle Management][1]
* [HTTP response status code][2]
* [HTTP request methods][3]
* [GraphQL][4]
* [API Days][5]
* [Smart Bear][8]
* [OpenAPI Initiative][7]
* [Using OpenAPI to Build Smart APIs for Dumb Machines][14]
* [RapidAPI][10]
* [Stripe][11]
* [Twillio][12]
* [OpenAPI Version 3 Specification][13]
* [Deploying My Postman OpenAPI to AWS API Gateway][15]
* [API 101][16]
* [OpenAPI Specification][17]
* [Getting Started WIth OpenAPI 3.0][18] 
* [Better API Design with OpenAPI][19]
* [Swagger Eidtor][9]


[1]: https://swagger.io/blog/api-strategy/what-is-api-lifecycle-management/
[2]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status
[3]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Methods
[4]: https://graphql.org/
[5]: https://www.apidays.co/
[6]: http://apievangelist.com/
[7]: https://www.openapis.org/
[8]: https://smartbear.com/
[9]: https://swagger.io/tools/swagger-editor/
[10]: https://rapidapi.com/
[11]: https://stripe.com/
[12]: https://www.twilio.com/
[13]: https://swagger.io/specification/
[14]: https://www.infoq.com/articles/openapi/
[15]: https://apievangelist.com/2020/01/02/deploying-my-postman-openapi-to-aws-api-gateway/
[16]: http://101.apievangelist.com/
[17]: https://github.com/OAI/OpenAPI-Specification/
[18]: https://swagger.io/blog/api-design/getting-started-with-openapi-3-0/
[19]: https://youtu.be/uBs6dfUgxcI