Bonita REST API documentation site

This project contains the sources of Bonita REST API documentation site.

A basic CLI based on NodeJS (cli/restdoc-site.js) is used to build the site. It is based on yargs project and expose the following commands :

• clean: delete previous build output

• build: generate the static site to deploy in specified output directory (default to ./build)

Requirements

Node 20.x (may work with newer versions, no guarantee).

While you can install Node from the official packages, we strongly recommend that you use nvm (Node Version Manager) to install and manage Node. Follow the nvm installation instructions to set up nvm on your machine. Go the cli folder, then run nvm use.

ℹ️	All commands are intended to be run from the repository root folder. The generated documentation is available in the build/ folder.

Don’t forget to run npm install the first time you build the project or on package.json changes.

Run commands

The CLI expose its usage via the --help option:

node cli/restdoc-site.js --help

The same option is available at command level:

node cli/restdoc-site.js <command> --help

Configuration and parameters

It is possible to configure some parameters from a JSON configuration file that you can pass via the --config argument to the CLI. In that case parameter from the configuration will be overridden by the CLI execution arguments.

# with a config.json file with {"a":"b"}
# 'a' will be equals to 'hello' in this sample
node cli/restdoc-site.js --config config.json myCommand -a hello

Build command

Simply run the following command line.

node cli/restdoc-site.js --config ./cli/restdoc-site.cfg.json build

Development mode

Simply run the following command line to get the development mode with live reload

node cli/restdoc-site.js --config ./cli/restdoc-site.cfg.json build -w -p 5050

CLI Configuration

Some argument are passed via the configuration files:

sourceDir

The source directory of the site to build

downloadUrlTemplate

The template url from where to download Bonita OpenAPI releases to publish

releases

The list of releases to publish

latest

If several releases are listed, you must specify which one is the latest

exemple

{
"sourceDir": "./site",
"downloadUrlTemplate": "https://github.com/bonitasoft/bonita-openapi/releases/download/${releaseVersion}/bonita-openapi-${releaseVersion}.zip",
"releases" : ["0.0.11"]
}

Static files

All files present in <sourceDir>/files will be copied to the root of the site with respect of the folder tree.

Templates files

All files present in <sourceDir>/templates with an .hbs extension are considered as Handlebars templates files and will processed accordingly. The data available to templates are the command arguments siteUrl, latest and releases and the properties of the <sourceDir>/templates/vars.json file.

Links

• Bonita OpenAPI : https://github.com/bonitasoft/bonita-openapi

• yargs : https://yargs.js.org/docs/#api-reference

• Handlebars : https://handlebarsjs.com/guide/