API documentation generator
JavaScript HTML CSS
Fetching latest commit…
Cannot retrieve the latest commit at this time.

README.md

lout Logo

API documentation generator for hapi

npm version Build Status Build status Dependencies Status DevDependencies Status

Lead Maintainer: Nicolas Morel

Description

lout is a documentation generator for hapi servers, providing a human-readable guide for every endpoint using the route configuration. The module allows full customization of the output.

Live demo

You can find a live demo of lout using the unit tests routes. The routes are of course fake but you can get a grasp of what lout looks like given various inputs.

Usage

Lout depends on vision and inert, make sure you register them with hapi.

const Hapi = require('hapi');

const server = Hapi.server({ port: 80 });

await server.register([require('vision'), require('inert'), require('lout')]);

server.start().then(
  console.log('Server running at:', server.info.uri)
);

Parameters

The following options are available when registering the plugin:

  • 'engines' - an object where each key is a file extension (e.g. 'html', 'jade'), mapped to the npm module name (string) used for rendering the templates. Default is { html: 'handlebars' }.
  • 'endpoint' - the path where the route will be registered. Default is /docs.
  • 'basePath' - the absolute path to the templates folder. Default is the lout templates folder.
  • 'cssPath' - the absolute path to the css folder. Default is the lout css folder. It must contain a style.css.
  • 'helpersPath' - the absolute path to the helpers folder. Default is the lout helpers folder.
  • 'partialsPath' - the absolute path to the partials folder. Default is the lout templates folder. This might need to be null if you change the basePath.
  • 'auth' - the route configuration for authentication. Default is to disable auth.
  • 'indexTemplate' - the name of the template file to contain docs main page. Default is 'index'.
  • 'routeTemplate' - the name of the route template file. Default is 'route'.
  • 'filterRoutes' - a function that receives a route object containing method and path and returns a boolean value to exclude routes.
  • 'apiVersion' - an optional string representing the api version that would be displayed in the documentation.

Ignoring a route in documentation

If you want a specific route not to appear in lout's documentation, you have to set lout settings for this specific route to false.

Here is an example snippet of a route configuration :

{
  method: 'GET',
  path: '/myroute',
  options: {
    handler: [...],
    [...]
    plugins: {
      lout: false
    }
  }
}

If you want to exclude multiple routes using conditions, you can use filterRoutes when registering lout :

server.register([require('vision'), require('inert'), {
  plugin: require('lout'),
  options: {
    filterRoutes: (route) => {
      return route.method !== '*' && !/^\/private\//.test(route.path);
    }
  }
}]).then(() => {
    server.start(() => {
        console.log('Server running at:', server.info.uri);
    });
});