The beauty of formally defined APIs

Part 1: Swagger/OpenAPI


As software developers we need to perform several tasks at the same time, coding, writing documentation and writing tests. And for every feature our current project requires we’ll perform, to a greater or lesser extent, all of these three things. So we can deduce that if we reduce the time spent in any of these activities we are then reducing the time that it takes our team to finish a feature.

Common cases that this post may be helpful in:

I’ll be focusing on client-server/frontend-backend apps, more specifically the link between the parts and how we can make this interface as smooth as possible. The two tools described below were chosen by personal experience. Do your own research to find the best fit for you, as there are hundreds of options.


It’s an open-source framework that helps us to design, build, document and consume HTTP APIs. It consists in a YAML document which holds all the definitions for our endpoints including their request and response objects.

We can then use our yaml definition to create client and server libraries, static documentation, interfaces for easy manual testing (like Swagger Editor ) and also tools for automated testing. But to be clear, you don’t need to use all of the available tools to get benefit from this framework, you can adopt it gradually and start implementing more things as the team becomes more comfortable with it.

A good startpoint in my opinion is having a generated client library and a generated HTTP framework for the backend:

But wait! You need to consider the following things before running into the office (or the Zoom/Google Meet/Jitsi/Microsoft Teams meeting) to tell everyone about it:

Stay tuned for a gRPC focused post!