TL;DR: The API definition and documentation must be in a separate repository.
Introduction
In the desktop or CLI apps era, you probably only had one folder where you would put all your code.
When the CVS arrived, you put that folder in version control.
With the Internet explosion, the develop paradigm turns into a client/server pattern.
In this case, it’s normal to split the project into two separate repositories: one for the backend/server and another for the frontend/client. Not?
There are several reasons to do that split.
For me, the most important is that the software cycle of each component is independent. Other reason is that you can have several clients or frontends (think in the one thousand Twitter clients, for example).
But as you know, to communicate the client with the server you need, normally, an API.
The answer to the question about where to put the API stuff is what we’ll try to resolve here.
The API Spec
In a good project, your API must be documented. Probably you use Swagger or OpenAPI Spec to do it.
Sometimes you prefer to use a auto-doc generator like as the included with…
