An automatic documentation generator for koa APIs. The goal is to make documentation easy using route specs that may already exist.
See example
folder for source code. View example output
> npm install --save koa-docs
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('/v1/docs', {
title: 'Pet Store API',
version: '1.0.0',
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 https://localhost:3000/v1/docs`);
});
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", etcpath
: required stringvalidate
header
: object which conforms to Joi validationquery
: object which conforms to Joi validationparams
: object which conforms to Joi validationbody
: object which conforms to Joi validationmaxBody
: max incoming body size for forms or json inputfailure
: HTTP response code to use when input validation fails. default400
type
: if validating the request body, this is required. eitherform
,json
ormultipart
output
: output validator object which conforms to Joi validation. if output is invalid, an HTTP 500 is returnedcontinueOnError
: if validation fails, this flags determines ifkoa-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. defaultfalse
handler
: required GeneratorFunctionmeta
: meta data about this route.koa-joi-router
ignores this but stores it along with all other route data
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 proivdeddescription
: 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 markdownextendedDescription
: 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.
- Render
extendedDescription
using markdown - Add
description
andextendedDescription
for groups - Ability to collapse/expand routes and groups
- Ability to switch themes and make default theme configurable
- More descriptive type descriptions for arrays and nested objects
- 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
- Multi version support