generator-barco-swagger-express v2.24.0

generator-barco-swagger-express

Yeoman generator to jump start a new NodeJS based project for creating a Rest API service.

It provides the following features:

• Uses Express, Swagger, Mongoose/MongoDb, Mocha
• Creates a new folder for your project with all boiler plate directories and files created
• Implements all common cross-cutting Barco/SILAD features that most micro-services will need
  (e.g. common logging format)
• Creates a starter Rest API definition file (Swagger) for a resource model name of your choice
• Implements an initial set of controller, service and model files for your resource that you can customize
• Creates a Mongoose Schema for the model resource
• Express routes are automatically created from your Swagger definition file
• Input validation automatically handled for your Swagger schema
• Generates a basic set of unit test cases that you can add to
• Sets up code coverage using NYC (Istanbul)
• Sets up an initial set of configuration files that you can extend (supports environment variables)
• Sets up eslintrc.json, .gitignore, README.md, etc. for your project
• Provides a way to pull in the latest versions of some key components of this generator into
  your ongoing project

Creating a new project

First install yeoman globally

npm install -g yo

Then git clone this module and run following commands:

cd generator-barco-swagger-express
npm link

Now in any top level work directory invoke the generator:

yo barco-swagger-express

This will ask you a series of questions that you should answer according to your project
requirements or accept defaults.

Of note is the first question "App Name". This you should set to your desired project name (no spaces).
A new directory with this name will be created containing all the generated code.

Another important question is the "Model Object Name". This you should change to your
primary resource name that you are building the CRUD based Rest API for.

Explore the generated project

After creating the project, it would provide sufficient code to immediately start trying it out.

First however you will need to ensure that an instance of MongoDB is running on localhost on standard port.

For example using docker:

docker run --name some-mongo -p 27017:27017 -d mongo

If you have MongoDb running, try starting the service.
Change to project directory and:

npm start

Or to start in development mode under Nodemon:

npm run start-dev

The app should start listening at the port you configured.

Try accessing the swagger documentation on your browser by visiting http://127.0.0.1:3000/docs

Run unit tests:

npm test

Run unit tests with coverage:

npm run coverage

After creating a new project, the directory structure would look somewhat like like this:

myapp/
├── api
│   ├── controllers
│   │   ├── bookController.js
│   ├── helpers/
│   ├── mocks/
│   ├── models
│   │   ├── bookModel.js
│   ├── services
│   │   ├── bookService.js
│   └── swagger
│       └── swagger.json
├── appHooks.js
├── app.js
├── config
│   ├── custom-environment-variables.json
│   ├── default.json
│   └── development.json
├── .eslintrc.json
├── .gitignore
├── logger.js
├── node_modules/
├── package.json
├── package-lock.json
├── README.md
├── test
│   └── test.js
└── .yo-rc.json

The Swagger API for your resource has been defined in api/swagger/swagger.json.
You will see that a basic model for your resource will have a name and description field.
APIs for create/get/modify/delete of the resource and browsing/deleting the resource collection
have been added.

Entry point code for implementing this API is found in api/controllers/bookController.js.
The controller code calls out to a service API found in api/services/bookService.js.
A Mongoose model for your resource is found in api/model/bookModel.js.
Unit tests for the API invocation can be found in test/test.js

Adding custom code

You can now start editing the swagger definition file found in api/swagger/swagger.json
to customize your API. Accordingly modify code in your model, service and controller files.
As you develop and add new functionality add new test cases to test/test.js.

A basic configuration of your project is defined in the config directory.
At the top of your config/default.json you can add custom config variables and use in your
application. Do not touch the "swagger" section.
Configuration that you want to be controlled via environment variables,
you can add to config/custom-environment-variables.json.

Update your README.md file to document runtime requirements.

Query filter

For retrieving resource lists, a simple SQL like query language is supported. Here are some examples:

Select items with name containing string 'hello'

"name REGEXP 'hello'"

Select items with name NOT having 'hello' AND description containing string 'world'

"NOT name REGEXP 'hello' AND description REGEXP 'world'"

Select items with name alphabetically greater than string 'xyz' and description containing string 'white' OR any item with description containing string 'yellow'

"name gt 'xyz' && description =~ 'white' OR description =~ 'yellow'"

Note: Without parenthesis, operator AND has precedence
Note: Operator 'REGEXP' has alias '=~'
Note: Operator 'AND' has alias '&&'

Similar to above but parenthesized. Retrieves any white and yellow items with name alphabetically > 'xyz'

"name > 'xyz' && (description =~ 'white' || description =~ 'yellow')"

Note: Operator 'OR' has alias '||'
Note: Operators 'eq', 'ne', 'lt', 'gt', 'le', 'ge' have aliases
'=', '!=', '<', '>', '<=', '>='
Note: Operator '<>' is another alias for 'ne' (besides '!=')

Select items where 'name' equals any of a list of strings (IN operator)

"name IN ('abc', 'xyz', 'lmn', 'pqr')"

Select items where 'name' is NOT IN a set AND have description containing string 'green'

"name NOT IN ('abc', 'xyz', 'lmn', 'pqr') && description =~ 'green'"

Select items with integer quantity > 20

"quantity > 20"

Note: No quotes around integers

Only operators '=' and '!=' are supported for booleans. The value can be a number (non zero is true) or case insensitive strings 'true' or 'false'.

Select items where field 'active' is true and field 'disabled' is false

"active = 'True' AND disabled eq 0"

The field names for query filter can be mapped to alternate names where the field
is actually stored in the MongoDb/Mongoose model by setting 'fieldMaps' property
in api/helpers/whitelist.js.

For example, for enabling field 'id', it needs to be mapped to '_id' like so:

module.exports = {
  strings: ["_id", "name", "description"],
  numbers: ["quantity"],
  fieldMaps: [
    ["id", "_id"]
  ]
};

Unit Tests

To add test case name into the log file, add one line to beforeEach block in your Mocha test.js file:

beforeEach(async function() { // Log current test name for easier debugging logger.info(UnitTest: ${this.currentTest.fullTitle()}); });