Diving into OpenAPI
Tags: api, webdev, startup, discuss
Published: 2019-02-24 10:48:36

---
title: Diving into OpenAPI
published: true
description: Diving into OpenAPI
tags: api, webdev, startup, discuss
canonical_url: https://www.maxongzb.com/diving-into-openapi-read-3-mins
---

![Photo by Shifaaz shamoon on Unsplash](https://thepracticaldev.s3.amazonaws.com/i/mjn5g0htevw804ovsu81.jpg)

# Introduction
At the start of this week, I started to go down and dirty to finally learn to use the **OpenAPI** editor as part of our API development process for a project we are working on in my work.

Despite being an **advocate** to use it to help in our **API development** process and it's usefulness for **documentation** to 3rd party developers to integrate our APIs whenever they are using our technology. 

# Documentation As Key to API Development
![thought-catalog-217861-unsplash](//images.ctfassets.net/ly2f59p4unnn/3AKdWL9AQVT88mYySLTHtF/6d379755faa7172aa43b22721c3057e9/thought-catalog-217861-unsplash.jpg)

Which after reading multiple articles on REST API development, **documentation** is one of the **key** reasons to help **drive** API adoption among developers or people with interest to adopt an API.

This was progress forward to building REST APIs using the OpenAPI specification as part of our development process. 

Since my knowledge in building APIs is mostly based upon tools like **Postman** and libraries like the **Django REST** framework. 

During that point of time, I did not see the need for OpenAPI until when I'm interacting with other developers in my company. 

Which comes down to **sharing** your API documentation as a **single source of truth**. 

So that **everyone** could work **towards** in **building & integration** of these APIs from either backend, frontend, freelancers or project managers point of view.

# What is OpenAPI?
![emily-morter-188019-unsplash](//images.ctfassets.net/ly2f59p4unnn/7fU8I8rAITEeWaptEsqHR5/096ccc878b43a2f8a3ffd0e5a2f74cc8/emily-morter-188019-unsplash.jpg)
OpenAPI has multiple names from Swagger or OpenAPI Specification. I was confused by it when I am going through articles or videos.

In short, OpenAPI is **text-based** documentation that produces a  **data visualisation** of your APIs without giving your source code to it. Which allows ease of integration and design of your APIs.

Based upon the **OpenAPI Specification** that was previously called **Swagger Specification** before their donation to the **Linux foundation**.

This specification was donated by a company called **SmartBear** who creates tools and eco-system surrounding the **Swagger Specification**. 

Till this date whenever you require an extensive list of tools for OpenAPI, you can always go to **Swagger** to learn about their tools to build your own OpenAPI documentation for your REST APIs.

# First Reaction of Using
![frank-mckenna-252908-unsplash](//images.ctfassets.net/ly2f59p4unnn/3BlT56nBFBo78gBrbkiDvr/73be45c063d55758823b29c9bee6b830/frank-mckenna-252908-unsplash.jpg)
The barrier for creating API documentation is **much easier** through the use of the **Swagger editor**.

As it comes with its own example API documentation in the older format that is **swagger 2.0**. Which allows you to get started with editing it to suit your needs.

While I am reading the example OpenAPI documentation, I stumble across a nice feature which is the **models** section.

This section provides **data structures** that could be used to create your own database based upon the APIs that is created.

If you are creating your first **OpenAPI documentation** I stick with **OpenAPI v3**. 

Since in version 3 of the OpenAPI Specification has been **drastically simplified** with additional **security sections** for each API like the use of OAuth or JWT. 

Fortunately, getting yourself started in **OpenAPI v3** is much easy as **Swagger** has provided the basic structure for you to get started in their documentation section called **basic structures**.

# Conclusion
![marc-olivier-jodoin-502572-unsplash](//images.ctfassets.net/ly2f59p4unnn/vECVhBWAAVrlDgfAtsB8C/3ac67e4c2cf5aa10abef2e6409a43529/marc-olivier-jodoin-502572-unsplash.jpg)

So far after spending a few hours of looking at the example documentation by **Swagger** and my colleagues I was able to grasp the understanding to implement the OpenAPI specification version 3.

Which allowed me to upgrade one of my colleagues OpenAPI specification file to version 3.

If your building **REST APIs** or has **existing APIs**, I would suggest you build **documentation** for your API so that it is much easier for **API adoption** by **developers** or **consultants** who are considering your API.

You can start with **OpenAPI** during the **design process** of your REST API or convert your APIs into OpenAPI through the use of **APImatic**. 

Lastly, OpenAPI is one of the industry standards that is widely being adopted by companies that use API like **Google**, **IBM** and **Google** with tons of tools like **Postman**.

# References
* [If A Search For Swagger or OpenAPI Doesn't Yield Results I Try For A Postman Collection][1]
* [OpenAPI Makes Me Feel Like I have a handle on What an API Does][2]
* [Open API Initiative][3]
* [Swagger][4]
* [Better Design WIth OpenAPI][5]
* [OpenAPI An Ebay Perspective][6]
* [OpenAPI: More than Just Documentation][7]

If you like my article either sign up for max [adventurer's newsletter](http://eepurl.com/dOUoUb) or you can **follow** to get the **latest** update of my article on **Dev** 

This post was originally posted on max's blog at [Diving Into OpenAPI - Read 3 Mins](https://www.maxongzb.com/diving-into-openapi-read-3-mins/) and [Photo by Shifaaz shamoon on Unsplash](https://unsplash.com/photos/AX4IP3j8cB0)

[1]: https://apievangelist.com/2018/07/16/if-search-for-swagger-or-openapi-does-not-work-i-try-postman-collection/
[2]: https://apievangelist.com/2018/04/18/openapi-makes-me-feel-like-i-have-a-handle-on-what-an-api-does/
[3]: https://www.openapis.org/
[4]: https://swagger.io/
[5]: https://www.youtube.com/watch?v=uBs6dfUgxcI
[6]: https://www.ebayinc.com/stories/blogs/tech/openapi-an-ebay-perspective/
[7]: https://konghq.com/blog/leveraging-openapi-awesome-apis/