This package has been deprecated

Author message:

deprecate...

@bcm-energy/bcm-api-generator

BCM API Generator

Version 1.3.0

The BCM API Generator is the tool to generate BCM Energy & Planète OUI backend architecture APIs.

---

Documentation · Guide for unit tests

The documentation, readme and guide assume that you are working on an unix like environnement

---

Summary

1. Usage
   1. Installation
   2. Usage
   3. Update & Publish NPM Script
2. Usage with the WebAPP
3. Documentation
   1. Run API
   2. API Endpoints
   3. SQL Database
      1. Launch Database
      2. Use Database in API
   4. Services
   5. Linter
   6. Production mode
   7. End to end Test
   8. Route Parameter Validation Middleware
4. Unit testing

---

1. Usage with NPM

   1. Installation

      The first thing to do is to install the package as global on your computer :

      npm install -g @bcm-energy/bcm-api-generator

      It should be the last version by default (currently 1.3.0), but if it's not you can force installation by using this command :

      npm install -g @bcm-energy/bcm-api-generator@1.3.0

   2. Usage

      Then you just have to launch the script that will generate a simple project:

      bcm-gen <folder path>

      ⚠️ Be careful, if you launch the script on an existing folder, files with the same name as those generated by the script will be erased

      If the folder does not exists, it will be automatically created. If it already exists, make sure you have the right to write on this folder.

      You can also add more option to the project like

      
      Adding a database

      bcm-gen <folder path> --db=<mysql|pg>

      
      Adding Listeners

      bcm-gen <folder path> --hasListeners

      
      Adding e2e test

      bcm-gen <folder path> --e2e

      
      Adding ESP option on the k8s file

      bcm-gen <folder path> --hasESP

      
      

   3. Update & Publish NPM Script

      If you want to publish an update, git clone the repository (https://github.com/BCM-ENERGY-team/bcm-api-generator), make your changes and create a pull request.

2. Usage with the webApp

   To use the web app you can directely access it through this URL

   http://start.beta.bcmenergy.fr/

   Or you can clone this project and launch it locally with the following commands :

   npm run dev

   or

   npm start

3. Documentation to launch the generated api

   1. Run API

      To launch the API you just need to run :

      npm run dev

   2. API Endpoints

      If you want to add an endpoint to your api, you just have to create a folder in app/api/your_folder/ and create the file index.js inside this folder.

      ./app/api/your_folder/index.js :

      module.exports = app => {
          app.get('/your_route', (req, res) => {
              res.status(200).send("Hello World");
          });
      }

      Then you have to edit the index.js file located on root folder and add the line to require your route folder.

      ./index.js :

      // ROUTER (line 15)
      ...
      require('./app/api/your_folder'); // <-- Your route file

      Test the route :

      curl http://127.0.0.1:3000/your_route # print Hello World

   3. SQL Database

      1. Launch Database

         By default the API does not have a database you will need to add the db option.

         To launch the postgres database, run :

         npm run test-db

         This script will create a postgres docker container, it will also execute all the .sql files located in ./test/sql/

         You just have to create or edit these files to run your own sql script.

      2. Use Database in API

         Make sure that you Env variables DB_HOST, DB_NAME, DB_USER, DB_PASSWORD, DB_PORT

         To make queries to the database, you have to require the connection file ../../database/postgres/db.

         Example :

         const db = require('../../database/postgres/db')(require('../../config'));
         
         let data = await db('t_trades').select('*'); // Asynchronous

         See knex documentation for more.

   4. Services

      The services folder is where you put your sources files that are not related to the database and that can be reused for others parts of your app.

   5. Linter

      To ensure that all of our APIs are formatted the same way, we use eslint, it's already configured, so you just have to run :

      npm run lint # print your errors
      npm run lint-fix # eslint can automatically fix some errors.

   6. Production mode

      While it's unlikely that you need this feature, it's possible to run the application in production mode :

      npm start

   7. End to end Test

      If you added the e2e parameter you will have a directory with the name e2e. In this directory you will put all your end to end test. The end to end test file name should respect the following format nameOfThetest .e2e.test.js

      To run the e2e test you have to run :

      npm run test-e2e

   8. Route Parameter Validation Middleware

      The API Generated has also a middleware that will allow you to validate the body of your different routes

      You will need to call the validate fucnction with a JSON Schema. JSON Schema is a vocabulary that allows you to annotate and validate JSON documentation. You can find more inforamtions on https://json-schema.org/

      const validate = require('../../middlewares/validate');
      
          app.get('/test', validate(require('./schemas/test.json')), async (req, res) => {...

4. Unit testing

   There are two ways to test the application :

   • Running the whole test suite in a dockerized stack
   • Running locally the test suite with a dockerized database

   Fully dockerized

   This is what will be run as part of the CI build validation. Running it can be achieved by doing:

   docker-compose up --force-recreate --build --abort-on-container-exit db-for-docker-test api-for-docker-test

   Or simply through:

   npm run test-docker

   This will spawn a database instance in a docker and the test will be run in a companion docker instance.

   Only database in container

   This is useful when we need to run tests often. Using this option, only the database is deployed in a container. One only needs to perform:

   docker-compose up --force-recreate --build --abort-on-container-exit db-for-docker-test

   The database can also be launched using:

   npm run test-db

   Contrary to running the database with docker-compose, when it's launched using npm, the containers are in background mode.

   When the database is up and running, one can run the test suite by doing:

   npm run test

   You may need to adjust your environment variables to point to this database instance.

   You will have a env file where you will find the password for the test database

   Coverage

   Along with testing the application, a good indicator is the test coverage.

   There are two ways to get the coverage

   Text mode

   npm run coverage

   You'll get a text output on the console showing the actual coverage. Something similar to:

   

   HTML mode

   npm run coverage-html

   You then need to open the output/index.html file to get a browsable HTML report such as: