json-schema-docs-generator

JSON Schema HTML Documentation Generator

A flexible solution for auto-generating HTML API documentation from JSON-schemas that take advantage of the v4 Hyper-Schema definition. To use this package, you must have at least one valid JSON-schema file, preferably one that implements the links definition of the Hyper-Schema spec.

What this package provides

Four main components are provided that can be combined to generate documented. Each of the components can be configued with a debugLevel of 0-4. The higher the debug level, the more verbose the output. This can help with debugging, specifically with resolving schemas.

Build example

Build the ecommerce example to see how schemas and templates are combined together:

git clone [e-mail]:cloudflare/json-schema-docs-generator.git
cd json-schema-docs-generator/examples/ecommerce
npm install
node bin.js
open dist/index.html

Template Driver

The provided template driver uses Handlebars to retrieve, compile, and register partial templates for the generating of documentation. To use your own template engine, simply adhere to the following interface:

The class implements a single method, fetch, as its interface. fetch is expected to return a Promise that will resolve with an object of compiled templates, keyed by file name. The included driver takes an array of file paths (or globs) of template files to retreieve and compile in its constructor.

Usage: Template Driver

var TemplateDriver = require('json-schema-docs-generator').TemplateDriver;
var driver = new TemplateDriver(['source/templates/*.handlebars'], {
 debugLevel: 1
});
 
driver.fetch().then(dosomething);

Schema Driver

A schema driver takes an array of file paths (or globs) of JSON schema files. It also implements a single fetch interface, which is expected to return a Promise that will resolve with an object of fully resolved schemas, keyed by schema the schema's id.

The heavy lifting is almost exclusively done by the Parser and Resolver classes, defined in lib/{parser,resolver}.js.

Usage: Schema Driver

var SchemaDriver = require('json-schema-docs-generator').SchemaDriver;
var driver = new SchemaDriver(['schemas/**/*.json'], undefined, {
 debugLevel: 1
});
 
driver.fetch().then(dosomething);

Composer

A Composer's job is to take templates and schemas, and produce HTML documentation. It will use the fetch interface on both drivers, and take the results of each to compose one or more pages that are configured.

The current implementation requirement for the provided Composer class is that the result from the TemplateDriver has a template with the name of base. See Composer.prototype.composePage for more the implementation details. Ideally a better solution could be found here. The base template will receive a data object with a page, containing the object defined by your page configuration. It will also contain navigation, which contains a reference to the currentPage object, as well as all other page objects under pages. The template payload will look something like this:

templatesObjectResolvedFromDriver.base({
  page: {
    file: 'index.html',
    title: 'Testing',
    schemas: [{
      .. resolved object ..
    }, {
      .. resolved object ..
    }]
  },
  navigation: {
    currentPage: { .. page object .. },
    allPages: { .. configuration from instantiation .. }
  }
});

You can build multiple pages by configuring page objects to group schemas together. Page objects can have any attributes you'd like for your templates. The only thing the Composer will help you do is swap out schema references for the fully resolved/transformed schemas. The composer will look for an array of schema IDs at the top level, or within each object of a sections array, for grouping one or more schemas that are related.

Usage: Composer

var Composer = require('json-schema-docs-generator').Composer;
var composer = new Composer(schemaDriver, templateDriver, {
  destination: 'htdocs',
  pages: [{
    file: 'index.html',
    title: 'Testing',
    sections: [{
      title: 'My schema',
      schemas: [
        '/some/schema'
      ]
    }]
  }]
});

Transformer

Transformer objects are geared towards preparing schemas for consumption by a template. Transormers are added via composer.addTransform(TransformClass). The composer will instantiate a Transformer class, provide it the full list of resolved schemas (for cross referencing).

The interface for transformer objects are via a .transform() method. This method should return all of the schemas provided to it on instantiation, with whatever modifications/transformations made by the class.

The provided transformer will do a handful of things to prepare schemas for the template, including providing an htmlID for each schema, for permalinks.

Other important transformations that happen are:

Object Definitions

Each schema object transformed will have an objectDefinition attribute, which as the following structure:

{
  allProps: {},
  requiredProps: {},
  optionalProps: {},
  objects: Array,
  example: string,
  _original: Object
}

If a schema utilizes oneOf or anyOf definitions, the sub-objects will be stored under objects. From here, each property is recursively defined with an example generated for each level.

Links

Links are augmented with the following properties:

{
  htmlID: string,
  uri: string,
  curl: string,
  parameters: ObjectDefinition,
  response: string
}

• uri: A resolved URI from the href attribute of the link, but simplifies any schema references to just the definition name. e.g., /some/endpoint/{#/definitions/identifier} => /some/endpoint/:identifer
• curl: A generated string containing an example cURL request for the endpoint. This will properly include schema information for all GET/POST/PUT/PATCH/DELETE methods.
• parameters: An object definition, as defined above, for the parameters of the link.
• response: An example response derived from the targetSchema of the link.

How to use

This package was built with the intent of being flexible. The process of autogenerating documentation has a lot of pieces, so a single class/configuration was too much of an abstraction to be easy to use.

Instead, the core components provided will hopefully be enough to extend, override, and adjust to meet most needs.

Below is the minimal setup:

var Docs = require('json-schema-docs-generator');
var schemaDriver = new Docs.SchemaDriver(['schemas/**/*.json']);
var templateDriver = new Docs.TemplateDriver(['source/templates/**/*.handlebars']);
var composer = new Docs.Composer(schemaDriver, templateDriver, {
  destination: 'htdocs',
  pages: [{
    file: 'index.html',
    title: 'Testing',
    sections: [{
      title: 'User',
      schemas: [
        '/user'
      ]
    }]
  }]
});
 
composer.addTransform(Docs.SchemaTransformer);
composer.build()
        .bind(composer)
        .then(composer.write)
        .catch(function(err) {
          global.console.log(err.message);
        });