Quick Start

This quickstart guide will use the Blackbox CLI and so you will need to start by opening a command line. The following commands assume that you have Node.js and have some familiarity with npm. By the end of this quick start guide you will have a fully functional web server that can serve a Blackbox web service (albeit with very limited functionality).

First, if you haven't already, install the CLI:

$ npm i -g blackbox-cli

Next, initialise the blackbox project - we will call our project "weather".

$ mkdir weather
$ cd weather
$ bb init -n weather -t "A weather API." --desc \
"An API for retrieving temperature and humidity information."

You should see the following output:

Created blackbox.json
Created openapi.json
Blackbox project successfully initialised.

This will create a blackbox.json configuration file and an openapi.json OpenAPI specification file. The -n (or --name) option sets the project’s name, the -t (or --title) option provides a title for the OpenAPI document, and the -desc option provides a description for the OpenAPI document.

We will now generate the web server:

$ bb generate server

Looking at the directory listing you should now see:

$ ls
README.md	blackbox.json	gensrc		gulpfile.js	index.ts	openapi.json	package.json	src		tsconfig.json

Briefly, blackbox.json and openapi.json are used for configuration of the services, gulpfile.js is used for building the solution, and index.ts is the root of our server application.

Install dependencies with npm:

$ npm i

Then build the solution:

$ npm run build

You should now have a dist directory with the built solution.

$ ls dist
api		gensrc		index.js

We can now start our server:

$ npm run start

You should see the following output:

> node dist/index.js

Your server is listening on port 8080 (http://localhost:8080)
Swagger-ui is available on http://localhost:8080/docs

If you visit http://localhost:8080 you should see the following in your web browser:

{
    "description": "A list of services provided by this API.",
    "bbversion": "0.0.2",
    "links": {
        "self": {
        "href": "/"
        }
    }
}