tsoa_sample v1.1.0
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
2 years ago