Example for APIDOC tools

exdoc.js

/**
 * Created by tines on 19/04/2016.
 */

'use strict';

var express = require('express');
var path = require('path');
var router = express.Router();
var middleware = require('../handlers/middleware');
var dataHandler = require('../handlers/data_db_handlers');


/**
 * @api {get} bus/busLocation /busLocation
 * @apiName BusLocation
 * @apiGroup Bus
 *
 * @apiDescription Returns a list of buses and their locations for a specified route.
 * @apiHeader {String} apikey User's API access key, which determines level of access. If API is public, token is not neccessary.
 *
 * @apiHeaderExample {json} Header-Example
 * {
 *  "apikey": "23676892-f992-46a9-b998-dd35290dbd69"
 * }
 *
 * @apiParam {Number} route_int_id Integer ID of route/ If no param is given, returns all available buses.
 *
 * @apiSuccess {Boolean} success Indicates success of GET request.
 * @apiSuccess {Object} data Array of JSON objects with bus data.
 * @apiSuccess {String} id bus ID.
 * @apiSuccess {Number} int_id bus ID.
 * @apiSuccess {String} reg_number Registration number of bus.
 * @apiSuccess {Object} geometry JSON object containing last known coordinates of the bus.
 * @apiSuccess {Number} station_int_id Integer ID of last known visited station.
 * @apiSuccess {Number} route_int_id Integer ID of route that the bus is currently on duty for.
 * @apiSuccess {String} utc_timestamp ISODate formatted timestamp of last location update.
 * @apiSuccess {String} local_timestamp ISODate formatted timestamp of last location update.
 * @apiSuccess {Number} unix_timestamp Timestamp of last update in UNIX epoch time (milliseconds).
 * @apiExample {curl} Example call:
 *     GET http://194.33.12.24/bus/busLocation?route_int_id=737

 *
 * @apiSuccessExample Success-Response:
 *     HTTP/1.1 200 OK
 *
 *    {
 *      "success": true,
 *      "data": [
 *        {
 *          "id": "6967904A-A25E-4236-9D35-0183BE08E1A7",
 *          "reg_number": "LJ LPP-238",
 *          "longitude": 14.5143,
 *          "latitude": 46.0757,a",
 *          "timestamp": "2016-08-23T10:28:11.000Z"
 *        },568a702ee",
 *        {
 *          "id": "756C53BB-CE1B-4575-9B8C-003612405C3F",
 *          "reg_number": "LJ LPP-432",
 *          "longitude": 14.4861,
 *          "latitude": 46.0753,
 *          "timestamp": "2016-08-17T09:58:23.000Z"
 *        }
 *       ]
 *    }
 *
 *
 */
router.get('/busLocation', middleware.userHasAccess, function (req, res, next) {

    dataHandler.busLocationsByRoute(req.query.route_int_id, function (err, data) {
        if (err) {
            res.status(400).send({success: false, msg: err});

        } else {
            res.send({success: true, data: data})
        }
        res.end()
    })
});


/**
 * @api {get} bus/busesInRange /busesInRange
 * @apiName BusesInRange
 * @apiGroup Bus
 *
 * @apiDescription Returns recently updated GPS coordinates of buses in specified radius of given location.
 * @apiHeader {String} apikey User's API access key, which determines level of access. If API is public, token is not neccessary.
 *
 * @apiHeaderExample {json} Header-Example
 * {
 *  "apikey": "23676892-f992-46a9-b998-dd35290dbd69"
 * }
 *
 * @apiParam {Number} lat Longitude
 * @apiParam {Number} lon Latitude
 * @apiParam {Number} [radius] Radius in meters, if missing defaults to 100 meters.
 *
 * @apiExample {curl} Example call:
 *      GET http://194.33.12.24/bus/busesInRange?radius=100&lat=46.056879&lon=14.505826
 *      GET http://194.33.12.24/bus/busesInRange?radius=100&lat=46.056879&lon=14.505826&radius=120
 *
 * @apiSuccess {Boolean} success Indicates success of GET request.
 * @apiSuccess {Object} data JSON object with list of buses in given area.
 * @apiSuccess {String} id bus ID.
 * @apiSuccess {Number} int_id bus ID.
 * @apiSuccess {String} reg_number Registration number of bus.
 * @apiSuccess {Object} geometry JSON object containing last known coordinates of the bus.
 * @apiSuccess {Number} station_int_id Integer ID of last known visited station.
 * @apiSuccess {Number} route_int_id Integer ID of route that the bus is currently on duty for.
 * @apiSuccess {String} utc_timestamp ISODate formatted timestamp of last location update.
 * @apiSuccess {String} local_timestamp ISODate formatted timestamp of last location update.
 * @apiSuccess {Number} unix_timestamp Timestamp of last update in UNIX epoch time (milliseconds).
 *
 * @apiSuccessExample Success-Response:
 *     HTTP/1.1 200 OK
 *
 *   {
 *     "success": true,
 *     "data": [
 *      {
 *        "int_id": 1976,
 *        "ref_id": "600012",
 *        "name": "Bavarski dvor",
 *        "longitude": 14.5051456871461,
 *        "latitude": 46.0561009080242
 *      }
 *      ...
 *       {
 *         "int_id": 1977,
 *         "ref_id": "600011",
 *         "name": "Bavarski dvor",
 *         "longitude": 14.505488014758,
 *         "latitude": 46.0562502760306
 *      }
 *     ]
 *   }
 *
 *
 * @apiError BadRequest Missing location params.
 *
 * @apiErrorExample Error-Response:
 *     HTTP/1.1 400 Bad Request
 *     {
 *       "success": false,
 *       "msg": "Missing location params."
 *     }
 */
router.get('/busesInRange', middleware.userHasAccess, function (req, res, next) {
    if (!req.query.lat || !req.query.lon) {
        res.status(400).send({success: false, msg: "Missing location params."});
        res.end();
        return;
    }

    var radius = !req.query.radius ? 100 : parseFloat(req.query.radius);

    dataHandler.busesInRange(parseFloat(req.query.lon), parseFloat(req.query.lat), radius, function (err, data) {
        if (err) {
            res.status(400).send({success: false, msg: err});
        } else {
            res.send({success: true, data: data})
        }
        res.end()
    })
});


/**
 * @api {get} bus/getNextStation /getNextStation
 * @apiName GetNextStation
 * @apiGroup Bus
 *
 * @apiDescription Returns the next station a bus will arrive to, based on previous station location. If not enough data is in the DB (null route or null previous station), system will return error.
 * @apiHeader {String} apikey User's API access key, which determines level of access. If API is public, token is not neccessary.
 *
 * @apiHeaderExample {json} Header-Example
 * {
 *  "apikey": "23676892-f992-46a9-b998-dd35290dbd69"
 * }
 *
 * @apiParam {String} bus_id Registration number of bus (LPP-101...). Characters are trimmed, only 3 digits are needed to identify the bus.

 *
 * @apiExample {curl} Example call:
 *      GET mustang.ijs.si:8000/bus/getNextStation?bus_id=LPP-101
 *      GET mustang.ijs.si:8000/bus/getNextStation?bus_id=LPP101
 *      GET mustang.ijs.si:8000/bus/getNextStation?bus_id=101
 *
 * @apiSuccess {Boolean} success Indicates success of GET request.
 * @apiSuccess {Object} data JSON object with station data.
 * @apiSuccess {Number} int_id Station identificator.
 * @apiSuccess {String} name Station name.
 * @apiSuccess {Object} longitude Station's geographical longitude.
 * @apiSuccess {Object} latitude Station's geographical latitude.
 *
 * @apiSuccessExample Success-Response:
 *     HTTP/1.1 200 OK
 *
 *
 *     {
 *       "success": true,
 *       "data": {
 *         "int_id": 3509,
 *         "name": "Koprska",
 *         "longitude": 14.4832452268611,
 *         "latitude": 46.0352461611615
 *       }
 *     }
 *
 *
 * @apiError BadRequest Missing location params.
 *
 * @apiErrorExample Error-Response:
 *     HTTP/1.1 400 Bad Request
 *     {
 *       "success": false,
 *       "msg": "Missing location params."
 *     }
 */
router.get('/getNextStation', middleware.userHasAccess, function (req, res, next) {
    if (!req.query.bus_id) {
        res.status(400).send({success: false, msg: "Missing bus ID parameter."})
        res.end();
    } else {
        dataHandler.getNextStation(req.query.bus_id, function (err, data) {
            if (!err) {
                res.send({success: true, data: data})
            } else {
                res.status(400).send({success: false, msg: err})


            }
        })
    }
});

module.exports = router;

instructions

Add documentation as in example in JS files in "routes" directory. Set APIDOC config file in root dir of project, then call following command

node node_modules/apidoc/bin/apidoc -i routes -o documentation/apidoc/


config (apidoc.json file)
{
  "name": "LPP-Docs",
  "version": "0.3.0",
  "description": "LPP API Server Project",
  "title": "LPP API Docs",
  "url" : "http://194.33.12.24/"
}