When you are developing an API and one or more developers (frontend, desktop, mobile, etc) will have to integrate their code with it, it’s very important to have it well documented so they know what and how they can use.

For that, in Node.js projects I’ve been using apiDoc, as it is able to generate documentation in HTML from annotations in the source code.

For this post, I’ll use the TODO List API I developed as an example, once more. So you can clone or download it from here.

This represents all our endpoints related to tasks in the system. How can we use them? What should the developers that will consume the API send to each of these endpoints?

So far there is no way for them to know other than looking at the code, which shouldn’t be needed.

Because of apiDoc, we can achieve that with annotations. The way I configure it, is by writing them before each endpoint configured in the files inside the routes directory. If you are not sure of what I’m talking about, check here when I mentioned how I configure and organize my Node.js projects.

As you can see, we have the HTTP method type (post, put, get, delete), the endpoint address, the api version, the kind of permission it needs, the params it requires, the response and the error if the user is not authorized.

In the official website you can check the documentation and available params for the annotations.

Where is this UnauthorizedError coming from?

apiDoc settings

There are some settings that can be done for apiDoc and this UnauthorizedError is the one I usually implement.

Create a file called _apidoc.js inside the routes directory with the following content: