Diving into OpenAPI - Read 3 Mins
📅 February 24, 2019
•⏱️4 min read
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
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?
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
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
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.