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:

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.