A node module to build the API console from the api-console element.
This module bundles required elements (web components and libraries) into single
bundle. It places API console sources in place where the
for the web component is defined.
You may be interested in using our CLI tool to build the API Console. Install the api-console-cli ang build the console with single command.
Using the module
This module provides you with tools to:
- build your own version of the API Console
- generate API documentation from the RAML file using latest (or any tagged release) version of the console
- tweak the build process to optimize loading time of the API console
const builder = ;;
Script above downloads that latest release of the API Console and use it to create a standalone web application that displays documentation from the RAML file.
All available options are defined in the BuilderOptions class. You can initialize options using simple map or options class:
const BuilderOptions = ;const options =dest: 'build'raml: 'path/to/api.raml';optionssrc = '';console; // prints false;
||String||Source of the API console. If the
||String||A release tag name to use. With this option the builder uses specific release of the console. If not set and
||String||Source index file, an entry point to the application. Don't set when downloading the
||Boolean||Set to true if the API console source (
||String||Output directory. Defaults to
||Boolean||If set, it will generate a JSON file out of the RAML file and will use pre-generated data in the console. Use this option to optimize console's load time. It will not include
||Boolean||Set to true to inline pre-generated JSON data in the main file instead of creating external JSON file. Only valid if
||Boolean||If true it will generate an import file for the web components that can be used in any web application. It will not generate a standalone application. Generated source file will contain an example of using the api-console on any web page. Defaults to
||String||The RAML file from which produce the documentation. If not set then it will generate a plain API console application without any documentation attached. Defaults to
||Boolean||If set it will not perform any code optimization. It will disable: comments removal, JS compilation, HTML minification, and CSS minification. It should be used only for development to reduce build time. Output will contain more data and therefore will be bigger. Defaults to
||Boolean||Disables CSS minification (CSS files and
||Boolean||Disables HTML minification. Also disables comments removal. Defaults to
||An array of attributes to set on the
||Boolean||Produces debug output to the console. Defaults to
Configuring the console - setting attributes
To set configuration option available for the
<api-console> element set a list
of attributes to the
For boolean attributes add the attribute name as a string. For attributes with values add a map where the key is an attribute name and value is attribute's value.
Note: Do not set
raml property here. It will be ignored. This option mast be set in general options map.
Note: Do not use camel case notation. It will not work. See the example.
const attributes ='proxy-encodeUrl''proxy': '''no-try-it''page': 'request'
Example above is the same as:
const attributes ='proxy-encodeUrl''no-try-it''proxy': '''page': 'request'
and produces the following output:
List of all available options can be found here: https://github.com/mulesoft/api-console/blob/master/docs/configuring-api-console.md
Building embeddable console
The API console can be embedded in your website or blog post. To build the console
from the RAML spec, use the
The output will contain two main files:
- import.html - bundled source code of the console
- example.html - shows an example of use
To embed the console on your website
- You have to include polyfill in the website's
- You have to import the
import.htmlfile as regular web component
- Place the
<api-console></api-console>anywhere on your website
- Initialize data depending on the build method. Examples of initialization are in the
Include the following polyfil in the
2. Import bundle
3. Place the console
The API console should be placed in a relatively positioned parent element with explicitly set height. Otherwise it won't renders correctly. By explicitly set height meaning either use of the height value in pixels or by using flex layout.
4. Initialize the data
This step depends on selected build method (with JSON or not, is JSON is inlined). See build example to see how to do it.
You can customize the API Console by creating your own html file that contains the
Example source file
As defined in the api-console element readme file.
<!-- index.html -->
This example omits the way of passing data to the
api-console. This has been described in the Passing the raml data section.
const builder = ;;
The module replaces imports section:
with actual content of imported files and their dependencies.
Because the API console is build out of the elements that require resources from the
bower_components folder with files that may be required by the application. Scripts from this folder will be loaded on demand.
Application based on the API Console loads a RAML file(s), parses it and generates JSON data that are recognizable by the console. This process can be slow and consumes lot of computing power. This can affect user experience, especially on mobile devices.
If the API spec doesn't change very often you can tell the builder to generate a JSON file out of the RAML spec and use it instead of parsing RAML content all over again. You have to set
useJson option when initializing the builder. It will generate a
api.json file that will be used by the API console.
If you are creating custom build then your application should handle JSON file load. See the standalone-json.tpl file for example.
inlineJson builder option. Note that this option currently is not working with custom builds.
Beta version notice
This is pre-relase version of the
api-console-builder and this module may
change in the future.
Current API is rather stable and we are not planning breaking changes.
Help us develop the API Console build tools! File an issue report for issues, feature requests for improvements. We'll be happy to hear from you.
GitHub requests limit exceeded error
GitHub API allows 100 request per hour. Because of this limit you may experience this error. You can expand the limit by setting
GITHUB_TOKEN system environment variable with a value of the GitHub personal token.