API Documentation is a concise reference manual containing all the information required to work with the API.

There are far many generator tools to create an API Documentation, such as apidocjs, swagger, slate, etc. It will make easier to generate and maintain the documentation for RESTful web APIs. On this occasion, i will share about how to create API Documentation with apidocjs.

What is apidocjs?

ApiDoc is inline Documentation for RESTful web APIs, apiDoc creates a documentation from API annotations in your source code. Furthermore, apiDoc gives you the ability to attach a version number to an API so you can easily track changes between versions.

How to write Documentation using APIDocJS?

# Preparation

To use apidocjs we need to install NodeJS including NPM, you can download it on nodejs.org and highly recommended install the LTS version. In my case, my desktop has installed nodejs version v12.13.0.

## Installation

Install apidocjs globally

npm install -g apidoc

## Configuration

Create a new file apidoc.json in your projects root directory includes common information about your project like title, short description, version and configuration options like header / footer settings or template specific options.

{
  "name": "Dream Technology",
  "version": "0.1.0",
  "description": "Dream Tours & Travel API Documentation",
  "title": "Dream Tours API Documentation",
  "url": "https://dreamtours.id/api/v1/",
  "header": {
    "filename": "header.md"
  },
  "footer": {
    "filename": "footer.md"
  }
}

you can create header.md and footer.md files on your root directory.

---

Create a new file example.js and insert this code below

/**
 * @apiDefine admin Admin access rights needed.
 * Only admin can perform operations.
 *
 * @apiVersion 0.1.0
 */

/**
 * @api {post} /payments/channels 1. Get Payment Channels
 * @apiHeader {String} apikey Users unique access-key.
 * @apiVersion 0.1.0
 * @apiName postPayments
 * @apiGroup Payments
 * @apiPermission admin
 *
 * @apiDescription Get all available payment channels.
 *
 * @apiExample Request (example):
 * 
    {
      "request":"Daftar Payment Channel"
    }
 *
 * @apiParam {string} request Request description
 * 
 * @apiExample Response (example):
 * 
   {
    "response": "Daftar Payment Channel",
    "merchant_id": "123456",
    "merchant": "Dream Tour",
    "payment_channel": [
        {
            "pg_code": "702",
            "pg_name": "BCA Virtual Account Online"
        },
        {
            "pg_code": "801",
            "pg_name": "BNI Virtual Account"
        }
    ],
    "response_code": "00",
    "response_desc": "Sukses",
    "status": "success"
  }
 * 
 */

A documentation block starts with /* and end with /.

This example describes a POST Method to request the payment channels.

@api {post} /payments/channels 1. Get Payment Channels is mandatory, without @api apiDoc ignores a documentation block.

@apiName postPayments must be a unique name and should always be used. Format: method + path (e.g. Post + Payments)

@apiGroup should always be used, and is used to group related APIs together.

@apiDefine defines a documentation block to be embedded within @api blocks or in an api function like @apiPermission.

@apiDefine can only be used once per block

---

Last Step

Open your terminal and execute this command (run every time you make changes in your code)

apidoc

After that your root directory has a new folder named doc

|   apidoc.json
|   example.js
|
\---doc
    |   api_data.js
    |   api_data.json
    |   api_project.js
    |   api_project.json
    |   index.html
    |   main.js
    |
    +---css
    +---fonts
    +---img
    +---locales
    +---utils
    \---vendor
        \---path-to-regexp

Simply open the index.html file to see the result or documentation page

---

Conclusion

APIDoc is an awesome tool to create a documentation for RESTful APIs easily and faster. Moreover, apiDoc gives you the ability to attach a version number to an API so you can easily track changes between versions. Kindly check the apidocjs documentation for more details.