tsoa_sample

TSOA Sample

by Alejandro M Pirola

This project is a monolithic service that provides a unified interface to all Numie services. fully implemented in Nodejs using Express. It uses TSOA to provide a clean and consistent API documentation, specification and client generation.

Requirements

Current nodejs version: v16.13.0

Install yarn npm install --global yarn

Installing all dependencies: yarn or yarn install

Visual Code Packages:

• REST Client

Folders structure

General

• /src: contains the source code of the project
• /build: contains the typescript compilation generated javascript code
• /client: contains all REST Client .http files for direct API calls.
• /test: contains the tests of the project
• /sample_data/gender_from_names: is a Big Query dataset to estimate statiscally gender probability based on person's name.
• /sample_data/kyc: has a dataset of INE/IFE ids and selfies to test OCR and face match capabilities.
• /sample_data/nufi: contains image in different sizes and responses in json format to test the Nufi service.
• /sample_data/templates: contains templates for Leap Scan Engine in json.

Source code /src

• /src/app.ts: app entry point. Service configuration such as Dependency Injection definitions, CORS, Swagger, etc.
• /src/config.ts: contains the configuration of the project. The env variables are loaded from:
  • /.env.dev.ini: env variables for dev.
  • /.env.prod.ini: env variables for prod.
• /src/controllers/: contains all the controllers of the project. Controllers are the entry points of the API. Each controller is created to cover a specific API feature.
• /src/authentication/: contains all the authentication related code. Handles the authentication and authorization of the API.
• /src/services/interfaces: has all the interfaces of the services. Such as persistsnce, logging, sms, etc.
• /src/services/implementations: has all the implementations of the services. Such as persistsnce, logging, sms, etc.
• /src/services/kyc: has all the KYC related services. Such as OCR, face match, etc.

Usage

Visual Code

This projects has 3 launch profiles in .vscode/launch.json. Press F5 to run project's profile with attached debugger. Crtl+F5 to run project's profile without debugger.

• Debug API: will launch the server ready to receibe requests at localhost port 3000.
• Debug all Tests: will execute all test inside /test folder.
• Debug Current Test: will execute the test file that is currently open.

Manual CLI Commands:

If you are using Visual Code, try to avoid using CLI commands.

TSOA Build routes

Any change in controllers regarding new methods or new paths o paths updates, requires a rebuild of routes. Routes are generated using TSOA annotations. Routes are the way this methods are aexposed through Express and Swagger. If you want to build routes manually, you can use the following command:

yarn run tsoa routes

Run server

node build/src/server.js

Generate OpenAPI specs file

yarn run tsoa spec

Clean TSC build

yarn run tsc --build --clean

Run Scripts from package.json

Build Everything

yarn run build

Run local for debug server

yarn run start

Production deploy in Google App Engine

In order to deploy execute the following command:

gcloud app deploy --no-promote --version gonzalez

Then open API Url in browser using:

gcloud app browse

Last url: https://numi-93f79.ue.r.appspot.com/

Deploy logs

gcloud app logs tail

TODO: add swagger.json to deploy.

Settings are in app.yaml file.

API Sharding

Above command allows to build and deploy the whole project in a single command. Usefull for testing the whole project. But... There is a subset of the API's controllers that are only available to partners As a Service. And there is another subset of the API's controllers that are available for Mobile Apps. In order to keep both projects in sync, we have a sharding mechanism that allows us to split the API's controllers in two differents builds. Each build has defferents spec and routes.

Each sharding has a typescript build script located on project's root. - ./spec_n_routes_consumer_api.ts: contains the spec and routes for the consumer API. - ./spec_n_routes_partner_api.ts: contains the spec and routes for the partner API.

Sharding: Register contollers

Register in the spec_n_routes_xxxxx_api.ts file the controllers that are available for each sharding.

Build API's

There is a couple of command line tools that can be used to build the API's.

Consumer API

Long story: This command will generate the specs and routes for the consumer API: yarn ts-node spec_n_routes_consumer_api.ts two files will be generated: - ./consumer/swagger.json - ./consumer/routes.ts Then you have to transpile the entrire project to javascript. This is done using the following command: yarn tsc --outDir ./consumer

Short story.... just run the following command:

Partner API

This command will generate the specs and routes for the Partner API: yarn ts-node spec_n_routes_consumer_api.ts two files will be generated: - ./partner/swagger.json - ./partner/routes.ts Then you have to transpile the entrire project to javascript. This is done using the following command: yarn tsc --outDir ./partner

Unit Tests

Visual Code

Try to use the launch profiles for unit tests:

• Debug All Tests
• Debug Current Test

Command Line

Execute tests in folder /test/*.test.ts yarn run mocha test.ts --require ts-node/register test/**/*.test.ts Or using package.json script config: yarn run test

For more information read: Mocha Docs at https://developer.aliyun.com/mirror/npm/package/mocha-typescript

Firebase ADMIN

This project requires Firebase Admin SDK to be installed. Is needed for data storage implementations.

Started from guide

https://tsoa-community.github.io/docs/getting-started.html#creating-our-express-server

Generate Numie SDK Clients

This projects uses TSOA to generate automatically OpenAPI 3.0 specs. Then is possible to generate clients for this API in any language that is supported by OpenAPI-Generator. Once all specs are generated, a file is created in the /build/swagger.json, this file contains all the information needed to generate clients.

Requirements

Install Open API Generator using: npm install @openapitools/openapi-generator-cli -g

Generate a Dart client

You can generate sdk in ../numie_sdk running this command line: yarn run buildgen

Also you can go more deep and execute the following command specifying the language and a different path. For example this line does exactly the same thing that the one above:

openapi-generator generate -i ./build/swagger.json -g dart -c config_openapi.yaml -o ../numie_sdk

• config_openapi.yaml: file containing Open API Generator settings.
• swagger.json: Open API spec file, generated by TSOA Express from numie_services/build