Back in 2018, I was assigned to build new tools for my team. This is one of the big project I got opportunity to work independently. Since It was first big project for me I had few things in my mind.

• Building Client-Server independently (not as mono repo)
• Using technologies which have good community support
• API first development

Challenges faced

So before starting any feature we all (small team of 3) with be discussing the API's which we are going to expose what are all the parameters API will consume and produce and will be documenting it properly internal word documentation. We were new to REST API development back then, we were not aware how to properly document the API's; due to this we had few issues:

• When one of the developer needed to make any changes, they ll announce us in our chat channel and update the changes. To learn what changes sometimes we were dependent on them.
• 6 months into the project another new developer had joined our team as the tasks were huge. Setting up the server was easier task as we had some script files but for mocking the existing API's it was bit difficult.
• We didn't had superb readable experience. What is the reason a parameter is given, whether it is mandatory, what is the data type, what are the acceptable values

Solution we Got

There is a famous saying

friend in need is friend indeed

this is true in my case. I was discussing with one of my friend, who had habit to explore lot of things and he suggested to check Swagger . In one of my previous article I have mentioned about OpenAPI specs. The name swagger was used until V2; from V3 we started using OpenAPI initiative once it came under linux foundation.

OpenAPI specs make it easy for both machines and users to read the JSON file and understand them. When the API documentation is written using OpenAPI Spec we can use it for generating client library, websites, or for testing.

This change the store entirely for us. From then we have changed our API documentation workflow.

• We will write the API document using OpenAPI Spec (JSON format)
• We can write locally in our machine in the VSCode itself
• We will push it to our central git repo

Better tooling for OpenAPI Spec writing

• VSCode
• Swagger viewer
• Git based repo (lot of git based workflows coming up, so better to stick with this)

Understanding diffs

Since we started using git version control (previously just a plain documents; now its bit more readable JSON files) we were able to see the git commits and difference between both the commits.

Easier developer On-boarding

For API development we are using Postman which is the awesome tools. As mentioned before, once the server is setup instead of copying and pasting manually each and every API URL and data, now we import the API JSON file (based on Open API specs).

Short cut: Ctrl + O

Easier read-ability

in VSCode we install Swagger viewer Extension which helps us to read the documentation easily.

We can also create the static website and publish to website.

To get started with OpenAPI check out the detailed documentation

Easier Automation testing

One of the developer authored a small program where we will read the spec document and validate the response and response codes.

In case if you would like to play around Open API specs in online, you can checkout swagger editor

Why OpenAPI spec is popular

• Easy to write REST API documentation. We can write in JSON format or YAML format.
• Better tooling for editing, viewing.
• Community support

OpenAPI spec has helped us to ease writing documentation for REST APIs, where we use for Client-server or certain Server-Server to communications. When we are going to use Asynchronous mode of communication we can check AsyncAPI