How to host jsdoc / apidoc on Express.js

Question

Im using http://apidocjs.com/ to create public documentation for an Express.js API that I am building. My question is, how do I use Express.js to route and serve the documentation?

Here's my Express server setup:

/** Load config into globally defined __config
 * @requires fs */
var fs = require('fs');
__config = JSON.parse(fs.readFileSync('config/config.json'));

/** Custom Logging Moduele
* @requires ninja_modules/jacked-logger */
log = require('./ninja_modules/jacked-logger');

/** Configure the Express Server
 * @requires express
 * @param {function} the callback that configures the server */
var express = require('express');
var app = express();
app.configure(function() {
    /** Sets default public directory */
    app.use(express.static(__dirname + '/public'));
    /** Sets root views directory */
    app.set('views', __dirname + '/public/views');
    /** Compress response data with gzip / deflate. */
    app.use(express.compress());
    /** Request body parsing middleware supporting JSON, urlencoded, and multipart requests. */
    app.use(express.bodyParser());
    /** Compress response data with gzip / deflate. */
    app.use(express.methodOverride());
    /** Set Express as the Router */
    app.use(app.router);
    /** .html files, EJS = Embedded JavaScript */
    app.engine('html', require('ejs').renderFile);
    /** Default view engine name for views rendered without extensions */
    app.set('view engine', 'html');

    /** Custom Error Logging
     * @requires ninja_modules/jacked-logger
     * @param {object} err - error object
     * @param {object} req - reqiuest object
     * @param {object} res - response object
     * @param {function} next - go to the next error */
    app.use(function(err, req, res, next) {
        log.error(err.stack);
        res.status(500);
        next(err);
    });
});
/** Set express to listen to the port defined in the configuration file */
var appServer = app.listen(__config.port, function(){
    log.sys("Express server listening on port " + appServer.address().port + " in " + app.settings.env + " mode");
});

// add documentation
app.use('/api', express.static(__dirname + '/public/documentation/api'));
app.use('/dev', express.static(__dirname + '/public/documentation/developer'));;

Here's my grunt file that I use to create documentation:

'use strict';

module.exports = function(grunt) {
    grunt.initConfig({
        jsdoc : {
            dist : {
                src: ['*.js', 'config/*.json', 'ninja_modules/*.js','workers/*.js'], 
                options: {
                    destination: 'public/documentation/developer',
                    private: true
                }
            }
        },
        apidoc: {
            ninjapi: {
                src: 'router/',
                dest: 'public/documentation/api/',
                options: {
                    includeFilters: [ ".*\\.js$" ]
                }            
            }
        }
    });
    grunt.loadNpmTasks('grunt-jsdoc');
    grunt.loadNpmTasks('grunt-apidoc');
    grunt.registerTask('default', ['jsdoc','apidoc']);
}

Does anyone know how I can host my documentation without declaring app.get('.. for every page? A tutorial somewhere would be great.

Thanks in advance.

Answer 1

My issue turned out to be that I was using __dirname in another file expecting it to be the root directory. This is obvious now that I think about it. If a file contains __dirname then __dirname = [the directory of that file] not the directory that the file (module) was required into.

This was causing look up errors.

Thanks for the help!

Answer 2

You don't need to declare routes for serving every static file.

This should be enough:

app.use('/api', express.static(__dirname + '/public/documentation/api'));

But if the public/documentation/api directory does not contain an index file, you'll get a request error.

So do this instead, which allows you to browse directories:

app.use('/api', express.static(__dirname + '/public/documentation/api'));
app.use('/api', express.directory(__dirname + '/public/documentation/api'));