This package has been deprecated

    Author message:

    deprecate...

    @bcm-energy/bcm-api-generator

    1.3.0 • Public • Published

    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:

      Text mode

      ### HTML mode

      npm run coverage-html

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

      HTML mode

    Keywords

    none

    Install

    npm i @bcm-energy/bcm-api-generator

    DownloadsWeekly Downloads

    31

    Version

    1.3.0

    License

    ISC

    Unpacked Size

    190 kB

    Total Files

    51

    Last publish

    Collaborators

    • bcmenergy
    • littleboyfr
    • lredondaud-bcm
    • meucci