/node-tsoa-example-api

Example Node TypeScript SOA API using external model module

Primary LanguageJavaScriptMIT LicenseMIT

Node TSOA example API

BuildStatus

Example Node API application with automatic generated Swagger documentation and static type checking on model objects, with model/request definitions shared via external versioned models module.

This repo is part of a collection of three repos that make up the entire example solution, web, api and models.

Uses TSOA to generate routes and swagger documentation based on decorated controllers and models. Provides a well structured Node API with type checked models and business logic with documentation aiding external parties to consume it. Services required by the controllers are injected into them using Dependency Injection via Inversify.

swagger

Based on tutorial from github example and here.

Requires:

  • NodeJS (v8+)

Overview

  • src/controllers - controllers for API
  • src/services - services used by controllers
  • src/errors - custom errors
  • src/swagger-ui - static html used for serving swagger documentation as html UI
  • src/routes.ts - TSOA generated routes from command npm run-script routes-gen
  • src/server.ts - start script for Express
  • src/ioc.ts - Inversify IoC container, see here for details
  • src/knexfile - Database configuration for knex query builder used in persistence and migrations
  • tsconfig.json - TypeScript config for tsc compile used to generate Javascript
  • tslint.json - TypeScript linting config setup to mimic StandardJS
  • tsoa.json - TSOA config, see here for details
  • dist - folder for generate JavaScript
  • dist/swagger.json - TSOA generated swagger doc from command npm run-script swagger-gen

Run

npm install
npm start # http://localhost:3001/docs

Debug

TypeScript compile generates maps, so you can debug the application using Chrome Dev tools against both TypeScript files and generated JavaScript.

npm run-script build
node --inspect dist/server.js # open chrome://inspect and connect to debugger

Updating models

The models module, used for DTO and request/response object definitions, is imported from a separate repository here.

To update, change the tagged version in package.json to required branch, e.g.:

"tsoa-example-models": "git+https://github.com/stevenalexander/node-tsoa-example-models.git#v0.1"

You can use a local path for the module, allowing local devleopment:

npm install --save file://src/node-tsoa-example-models
# "tsoa-example-models": "file:../node-tsoa-example-models"