Как разместить jsdoc/apidoc на Express.js

Я использую http://apidocjs.com/ для создания общедоступной документации для API Express.js, который я создаю. Мой вопрос: как мне использовать Express.js для маршрутизации и обслуживания документации?

Вот моя настройка сервера Express:

/** 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'));;

Вот мой файл grunt, который я использую для создания документации:

'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']);
}

Кто-нибудь знает, как я могу разместить свою документацию, не объявляя app.get('.. для каждой страницы? Где-то учебник был бы отличным.

Заранее спасибо.


person RachelD    schedule 28.08.2013    source источник


Ответы (2)


Вам не нужно объявлять маршруты для обслуживания каждого статического файла.

Этого должно быть достаточно:

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

Но если каталог public/documentation/api не содержит индексного файла, вы получите ошибку запроса.

Так что сделайте это вместо этого, что позволит вам просматривать каталоги:

app.use('/api', express.static(__dirname + '/public/documentation/api'));
app.use('/api', express.directory(__dirname + '/public/documentation/api'));
person badsyntax    schedule 28.08.2013
comment
Если вы используете какой-либо тип аутентификации, такой как jwt, строка app.use(.. должна быть перед использованием промежуточного программного обеспечения JWT/auth. - person avck; 06.06.2016

Моя проблема заключалась в том, что я использовал __dirname в другом файле, ожидая, что это будет корневой каталог. Это очевидно сейчас, когда я думаю об этом. Если файл содержит __dirname, то __dirname = [the directory of that file] не является каталогом, в который требуется файл (модуль).

Это вызывало ошибки поиска.

Спасибо за помощь!

person RachelD    schedule 28.08.2013