Node Tutorials Articles

How to create REST API Documentation using apiDoc?

apiDoc is free and poweful tool to create rest api documentation. Lets implement it in Node.js

Lets create node js project.

create folder apidocumentation and enter into it.

cd apidocumentation

Now follow below steps

npm init

Installed required packages

npm i express;
npm i body-parser;
npm i apidoc;
npm i ejs;

create index.js

const express = require ('express');
const bodyParser = require ('body-parser');
const app = express ();
app.get ('/', (req, res) => {
  res.send ('silence is golden');
});
// To create static path
app.use(express.static(__dirname + '/public'));
// To render static HTML Pages using express
app.engine('html', require('ejs').renderFile); 
app.set('view engine', 'html'); 
// Listening on PORT
const port =  9001;
app.listen(port, () => console.log(`Listennin on port ${port}..`));

create apidoc.json file

{
    "name": "apidocumentation",
    "version": "0.1.0",
    "description": "REST  API  Documentation Demo",
    "title": "Rest API Documentation",
    "url" : "https://localhost:9001/apidoc"
  }

create a folder src and create api.js into it

/**
 * @api {get} /user/:id Request User information
 * @apiName GetUser
 * @apiGroup User
 *
 * @apiParam {Number} id Users unique ID.
 *
 * @apiSuccess {String} firstname Firstname of the User.
 * @apiSuccess {String} lastname  Lastname of the User.
 *
 * @apiSuccessExample Success-Response:
 *     HTTP/1.1 200 OK
 *     {
 *       "firstname": "John",
 *       "lastname": "Doe"
 *     }
 *
 * @apiError UserNotFound The id of the User was not found.
 *
 * @apiErrorExample Error-Response:
 *     HTTP/1.1 404 Not Found
 *     {
 *       "error": "UserNotFound"
 *     }
 */

Now create public/apidoc folder and run

apidoc -i src/ -o public/apidoc

above command will create all required content into apidoc folder

run

node index.js

visit

http://localhost:9001/apidoc

your documentation will be ready.

Further how to add description,form, requests, response can be seen from here https://apidocjs.com/

Leave a comment