api-console-dev-preview

A npm module to generate API console dev version from RAML files and update RAML data every time the sources change.

It runs development version of the API console (without optimization for production) with RAML documentation from pointed directory and observes this directory for changes. Each time any file changes it updated the API console without reloading it.

Example

const {ApiConsoleDevPreview} = require('api-console-dev-preview');

const server = new ApiConsoleDevPreview({
  projectRoot: '/path/to/api/directory/',
  api: 'my-api.raml',
  src: '/console/sources/api-console-full.zip',
  sourceIsZip: true,
  noBower: true,
  verbose: true,
  open: true
});
server.run();

Script above runs a web server with the API console and observes /path/to/api/directory/ path for any change. If content of the directory change then the console is updated without reloading the page.

The api-console-full.zip file contains API console sources with installed bower components. With noBower is significantly speeds up start time. If this values are not specified then the module downloads API console sources from GitHub and installs bower dependencies. Note that this operation may take several seconds to finish.

The open option tells the server running script to open default browser with the API console url.

Options

Some of the options are the same as in the api-console-builder module.

Option	Type	Default	Description
`api`	`String`	`api.raml`	The RAML entry point file.
`host`	`String`	`undefined`	Host name of the web server.
`noBower`	`Boolean`	`false`	If set to `true` it skips bower components installation. Use it if `src` points to an `api-console` sources with all dependencies installed.
`open`	`Boolean`	`false`	If set it opens browser window when console is ready.
`port`	`Number`	`undefined`	Port name of the server.
`projectRoot`	`String`	Current working directory	API project folder location.
`sourceIsZip`	`Boolean`	`false`	Determines that local API console source is in zip file. See also api-console-builder options.
`src`	`String`	`undefined`	API console sources in local or remote location. If sources are at remote location it must be a zip file. See also api-console-builder options.
`tagVersion`	String	`undefined`	A release tag name to use. With this option the builder uses specific release of the console. If not set and `src` is not set it uses latest release. Note, only versions >= 4.0.0 can be used with this tool. See also api-console-builder options.
`verbose`	`Boolean`	`false`	Prints debug messages

API console sources resolution

By default the module downloads latest release of the console from GitHub and use it to generate the preview.

If custom version of the console is to be used to generate the preview or to reduce startup time use the src option to point to console's release.

If it points to a local directory it's content will be copied to web server destination.
If it points to a local zip file set sourceIsZip option. Zip file content will be extracted to server's working directory.
If it points to a remote location the module expects it to be a zip file (sourceIsZip option is then assumed by default).

const options = {
  src: '/console/sources/api-console.zip',
  sourceIsZip: true, // false by default, for directories with extracted console
};

API console downloaded from GitHub required to install bower dependencies. When server startup command is called the script runs bower install command to download the dependencies. Bower is installed by the script locally. This operation may take several seconds. If that's a limitation for some use cases then you can prepare a zip file with console's source code and installed bower components. In this case set noBower option to prohibit downloading the dependencies.

const options = {
  src: 'api-console-full.zip',
  sourceIsZip: true,
  noBower: true
};

Additionally the module can download specific release of the console. Use tagVersion option for that.

const options = {
  tagVersion: 'v4.0.0'
};

Using the module

After running the start command the process continue in background. Info message is printed to the terminal with the address of the API console:

Bash terminal

To terminate the thread and clean up allocated resources press ctrl + c.

When the command is running it observes path specified in the projectRoot option. Whenever file is changed, added or deleted the module regenerates data used by the console and sends it to the console.