02 - Generator


This page provides information on how to generate a microservice using NPM and Grunt from the files that were created and provided by the output from step 01 - Swagger editor.

The previous step, created the main files and the recipe needed to create a microservice. In this step, we just need to run NPM and Grunt so that the recipe gets applied and generate the files and folders that will hold the business logic of our microservice.

The folder/files and code structure relies on the soajs.composer that gives us the flexibility to create and modify a microservice without the need to maintain the REST Layer, Model Injection at run-time or Initializing and closing database connectivity.

This means that the folders and files will be generated to be composer dependent. To learn more about the composer click here.

Generated Files

Step 01 - Swagger editor generates a list of files for us, puts them in a folder, zips the folder and returns it to us.

Attached you find a sample of a microservice that was generated in that step.

The generated files are not final, you still need to run a final command to run the build recipe.


Download the zip file and extract it, then open your terminal and run the following commands:

Build Your microservice
$ cd your_new_service_extracted_folder
$ mkdir node_modules
$ npm install
$ grunt build

The above will create a folder "node_modules" inside your service extracted folder, download all the dependencies needed inside it and finally run a grunt build command that populates the final list of files and folders for your microservice.

On build, we will create the following files :

  • Update the config.js file and add all your APIs.
    • Each API will point to a middleware file located in a new generated folder lib/mw where you should write your business logic.
  • Generate a new folder lib that contains sub-folders:
    • models: where we should create you database models pending on your database information captured in the service information tab of step 1. Inside each model, you will find all the functions written and ready to for usage: save, update, find, insert, etc... . Simply enter the database name and collection at the top of the file where instructed or pass them as dynamic values from the business logic inside lib/mw files.
  • Generate a test folder that contains the necessary files and folders so you can write and run your test cases with the help Grunt.

Attached you find a sample of schema after we ran the above commands on the sample mentioned in the above section.

Fill in the Business Logic

Once you run the commands above, all you need to do now is open each middleware file and write the business logic inside it.

Each API points to a middleware file named after the route and method of the API; both the method and route where extracted from the swagger.yaml file which contains the YAML code you entered in the Swagger UI Editor in step 01 - Swagger editor.

  • Do not change the files name after the first generate.
  • Do not change the service name after the first generate.
  • Do not change the folder schema after the first generate.

Update a microservice

After you build your service, you can always modify it.

When you modify a service, you can add/update or remove APIs. and you can do that very easily.

Simply update the swagger.yml YAML code with your new changes and run the below command.

Regenerate Microservice folders/files
$ cd your_new_service_extracted_folder
$ grunt rebuild

When you rebuild, the generator keeps all your existing middleware files.it does not delete them or replace them.

This means if you kept an API untouched or removed an API from your YAML code, the middleware file will still be there.

If you renamed an API route or changed its method, a new middleware file is generated, so make sure you cater for the business logic code update.

The generator also rewrites the config.js file.

This also means that after you rebuild, all that is needed is for you to fill in the business logic of the APIs.