koa-docs

An automatic documentation generator for koa APIs. The goal is to make documentation easy using route specs that may already exist.

* Usage
* API:
* docs.get()
* That's it (just one method)
* Specs:
* Groups
* Routes
* Links:
* Github repo
* Sample output

Demo

See example folder for source code. View example output

!Screenshot

Install

> npm install --save koa-docs@2.x.x

Note version 2.x.x of this package uses joi router version ^3 specs; use version 1.x.x of this
package if you are using older specs

Usage

``javascript
const app = require('koa')();
const docs = require('koa-docs');

// Create a path for viewing the docs (only GET method is supported)
app.use(docs.get('/docs', {
title: 'Pet Store API',
version: '1.0.0',

theme: 'simplex', // Specify a theme from www.bootswatch.com;
// default is un-themed bootstrap

routeHandlers: 'disabled', // Hide the route implementation code from docs

groups: [
{ groupName: 'Pets', routes: [/ ... route specs ... /] },
{ groupName: 'Store', routes: [/ ... route specs ... /] }
]
}));

app.listen(3000, (err) => {
if (err) throw err;
console.log(Docs are available at http://localhost:3000/docs);
});
`

docs.get(path, options)

Creates a koa middleware which generates and serves api documentation
using the specs provided in the options object.

Arguments

1. path (String): the GET path at which the documentation will be served
2. options (Object)
- title: string representing the page title; displayed at the top of the docs
- version: string representing api version; also displayed at top of the docs
- routeHandlers: string indicating whether to show the route handler code in the docs. Options are __disabled__, __expanded__ or __collapsed__ (collapsed is the default)
- theme: string name of a theme from bootswatch to be used as the default theme
- groups: array of group specs as described below

Returns

(GeneratorFunction): Middleware suitable for use in koa.js app

Group specs

Groups are used to logically display the various sections of your api. They are declared as follows:

- groupName: string representing the name of the group
- description: string that describes the group; keep this short at about 1 scentence. This is displayed in both expanded and collapsed states as well as in tooltips. This should be a simple string; no markdown
- extendedDescription: string that supports markdown and is displayed only in when a group is being displayed in an expanded state. Make this as long as you need.
- prefix: optional string to be prefixed to all route paths in this group
- routes: array of route specs representing the routes in this group. See below for details on route specs.

Route specs


The route specs are the same as koa-joi-router, therefore, those routes can be used directly with koa-docs. Specifications are as follows:

- method: required HTTP method like "get", "post", "put", etc
- path: required string
- validate
- header: object which conforms to Joi validation
- query: object which conforms to Joi validation
- params: object which conforms to Joi validation
- body: object which conforms to Joi validation
- maxBody: max incoming body size for forms or json input
- failure: HTTP response code to use when input validation fails. default 400
- type: if validating the request body, this is required. either form, json or multipart
- output: output validator object which conforms to Joi validation. if output is invalid, an HTTP 500 is returned
- continueOnError: if validation fails, this flags determines if koa-joi-router should continue processing the middleware stack or stop and respond with an error immediately. useful when you want your route to handle the error response. default false
- handler: required GeneratorFunction
- meta: meta data about this route. koa-joi-router ignores this but stores it along with all other route data

$3

In addition to the above options, koa-docs looks for the following properties in the meta object of each route:

- friendlyName: string which is used in the sidebar and route title; route path is used if this is not proivded
- description: string that describes the routes; keep this short at about 1 scentence. This is displayed in both expanded and collapsed states as well as in tooltips. This should be a simple string; no markdown
- extendedDescription`: string that supports markdown and is displayed only in when a route is being displayed in an expanded state. Make this as long as you need.

$3

* pets example
* store example

Roadmap / Contribution

Please feel free to claim any of the following features for development; more
features can be requested by opening an issue.

* [ ] Create separate section for models (joi objects that have a label)
* [ ] Add popovers for displaying models
* [ ] Quick filter (fuzzysearch)
* [ ] Ability to save the generated HTML to file
* [ ] E2E testing of output

License

MIT