The resourcer-docs from koajs

resourcer-docs's Introduction

#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.