TL;DR: The API definition and documentation must be in a separate repository.
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
Sometimes you prefer to use a auto-doc generator like as the included with RapidAPI framework.
If you use gRPC, you must to write a “.proto” file at least.
In any case, where do you put that API stuff?
In many cases the answer is: in the server side.
But the question is: Is it the best place?
Short answer: Not (not for me).
The API Spec is the most important contract in the project.
In many projects, it’s even the first deliverable item.
With the API spec done, the server team and the front end team can start to work.
The frontend team can use tools to create stubs and mocks using the API Spec.
By the other hand, you can have several server implementations, and each one can implement the same or versioned API spec.