74. Documenting the API

In this video, we're going to start documenting our server source code so that apiDoc can generate the content for our API documentation website.

Where to document the API

The purpose of our documentation is to describe the endpoints of our API, including the URL, HTTP method, the request parameters required, the response to expect, and so on.

All this information will need to be specified in doc blocks in our source code. So where do we put all that?

Give the MVC structure of the PrintBay API, I think the best place for this info is in the router files.

You'll see I've already added a doc block about the above the line .get(ItemController.fetch) which would provide documentation for the GET /items endpoint.

In case you haven't used doc blocks before, they're a type of comment that always begin with a double asterix in order to distinguish them from regular comments.

@api

When our apiDoc Grunt task runs, it will scan through the router files of our server, and it will parse any line in the doc blocks which begins with a valid apiDoc param.

You'll learn many different apiDoc params over the next few videos, but the one we always begin with is this one, which is simply just @api.

Very similar to the way a method works in code, you need to place a certain sequence of values after an apiDoc param in order to use it correctly.

The first value after the param is the API method which goes inside a curly brace. This should be the HTTP verb used by the endpoint you're documenting. This is a GET route, so that's why I've put {get}.

The second value is the path of the endpoint, which in this case is /items. Finally, we can put an optional description of the endpoint, which in this case is "Fetch all items".

server/routes/items.js

/**
 * @api {get} /items Fetch all items
 */
.get(ItemController.fetch)

Testing

Looking in the browser, you'll see how apiDoc has used that information to partially document that endpoint. We're now going to add several more apiDoc params to complete the documentation.

@apiGroup

The next param we're going to add is @apiGroup. This defines the group to which the endpoint belongs.

The PrintBay API currently has two resource types: items and users. So we'll simply use Item as the group for this endpoint, as we will for all the endpoints in the item file.

server/routes/items.js

/**
 * @api {get} /items Fetch all items
 * @apiGroup Item
 */
.get(ItemController.fetch)

Testing

Now that we've added a group, you'll see our endpoint is now properly grouped under the subheading Item. As we start adding more endpoints, they'll all be logically grouped in this way.

@apiName

The next param we're going to add is @apiName, which allows us to provide a unique name for the endpoint. Technically, this can be anything you like, but the best practice is to use the format "method + path" in Pascal case. So let's give this one the name GetItems.

server/routes/items.js

/**
 * @api {get} /items Fetch all items
 * @apiName GetItems
 * @apiName GetItems
 */
.get(ItemController.fetch)

The main purpose of the name param is to give a unique anchor ID to the endpoint in the generated docs.

So if we click the name of our endpoint in the sidebar menu, you'll see the name has been used in the path.

This is handy because it allows you to hyperlink to this specific endpoint if the docs are deployed.

Discussion

0 comments