Setting up apiDoc

In the first half of this module we'll be creating our API documentation using the tool apiDoc.

apiDoc will generate a static website containing our API documentation. It bases this on the inline documentation we're going to put in our source code which will describe the features of our API.

Config file

Let's begin by creating a JSON config file for apiDoc by going to the terminal and typing:

$ touch apidoc.json

Let's now add the basic config we'll need in this file. We'll begin by creating an object, and then we'll add a "name" property and assign the name of our API which is, of course, "PrintBay".

We'll then add a "version" property. We can set that to "1.0.0". Next well add a "description" which will simply be "API docs".

We'll add a "title", "PrintBay API", which will be used as the title of the generated website. And, finally, we'll add a "url" property which we'll make "http://localhost:8080". apiDoc will use this as the base URL for the endpoints in the documentation.

apidoc.json

{
  "name": "PrintBay",
  "version": "1.0.0",
  "description": "API docs",
  "title": "PrintBay API",
  "url" : "http://localhost:8080"
}

Serving the docs

Now that we have a config file, we can manually generate the docs site using the apiDoc CLI. However, it's a much easier development experience to have a development server, preferably with live reloading.

To do this, we'll use the apiDoc Grunt plugin. If you've never used Grunt before, it's a task runner that, while still in use now, was most popular a few years ago before Webpack became the tool of choice for creating build pipelines like this.

Gruntfile

I've already added the Grunt configuration to the root directory of the project, as well as all the necessary NPM module. So be sure to check out the module 7 source code and run NPM install before continuing.

So let's quickly review this Gruntfile. There are three distinct tasks that this file defines. Firstly, the apidoc task which generates the docs site based on the code it finds at this path.

Secondly, the http-server task will serve the generated docs site on port 8050.

Thirdly, the watch task will watch our code for changes, triggering the apidoc task to run again.

Opening the site

Let's now run the Gruntfile by going to the terminal and typing:

$ npx grunt

Assuming it worked, we should be able to go to the browser now and open http://localhost:8050, and you should now see the skeleton of the API docs.

NPM tasks

Rather than directly running the grunt task directly, let's add some NPM scripts.

The first script we'll call "docs:server:api", and the command for that is simply "grunt".

We'll also add a command "docs:build:api" and the command for this will be "grunt apidoc". The purpose of this command is to simply build the docs without running the dev server.

package.json

{
  ...
  "scripts": {
    ...
    "docs:serve:api": "grunt",
    "docs:build:api": "grunt apidoc"
  },
  ...
}

With that done, let's run "docs:serve:api" so we're ready to start development.

$ npm run docs:serve:api

Live reload

Before we start filling out the documentation, let's make sure we get live reloading working for our docs site, so that when we make a change to the source code, the docs site reloads automatically to reflect the change.

Now, with a Webpack dev server, we get live reloading out of the box, as Webpack builds a socket client into the generated source code during development.

Grunt doesn't work the same way, so unfortunately don't get this feature out of the box. Instead, what we're going to do is install a browser plugin called LiveReload.

You can get this by going to livereload.com/extensions and finding the extension appropriate for your browser.

I've already configured the Gruntfile so that the development server will communicate with this extension, so all you need to do is install it and it will, hopefully, work.