Awesome
#resourcer-docs
A simple documentation generator for koa-resourcer.
Use
In your app:
var koa = require('koa');
var join = require('path').join;
var resource = require('koa-resourcer');
var docs = require('koa-resourcer-docs');
var app = koa();
resource(app, join(__dirname, 'resources'), docs.addRoute);
app.listen();
In each resource app:
var koa = require('koa');
var Router = require('koa-joi-router');
var router = Router();
var app = module.exports = koa();
// Expose routes to documentation generator
app.routes = router.routes;
// Define some routes...
app.use(router.middleware());
Configuration
Add a description to the route config:
router.get('/', {meta: {description: 'Home page'}}, function* () {
this.body = "Home page under construction since 2009";
});
Hide a resource by not exposing routes:
// Expose routes to documentation generator
//app.routes = router.routes;
Hide individual routes in a resource app from documentation by adding hide: true to route metadata:
// Documented route:
router.get('/', {meta: {description: 'Main route'}}, function* () {
this.body = 'Hello world';
});
// Hidden route:
router.get('/secretRoute', {meta: {description: 'Nobody here but us chickens.', hide: true}}, function* () {
this.body = 'This is a hidden world';
});
Add middleware to intercept requests before routing to docs:
var docs = require('koa-resourcer-docs');
// Respond with 404 if not in a development environment
docs.useRequestHandler(function* (next) {
if (process.env.NODE_ENV === 'development') {
return yield next;
}
this.throw(404);
});
For backwards compatibility "hide" and "description" on the koa-joi-router configuration object are still supported but no longer recommended since they pollute the namespace of the configuration.
Installation
npm install koa-resourcer-docs --save