Note: If you wanted to see how generated application will look like see mongoDB base user-service and SQL based user-service
RESTful API generator with swagger integration using NodeJS and Express. This project generates afull fledge rest app powered by express. The idea of this project is to bring up your microservices fast, with inbuilt request validations, connection to the database and fully working rest APIs To see all the application features, see feature section:
Following backends are supported
- Non-CRUD (Without any database, just simple get call)
- MongoDB
- MYSQL
It supports SQL and MongoDB now, but other databases support is on the way
This section list all major frameworks/libraries used in this project.
- Non CRUD Application
None - CRUD Application
Specific database needed, let's say you are running MYSQL based app then MYSQL server needed, for more details see your generated app
Go to your command-line interface and type npm install -g yo generator-rest-swagger-express
Go to your command-line interface and type yo rest-swagger-express and answer the prompts.
If the generator is installed correctly, your prompt should looks :
$ yo rest-swagger-express
? Your service name myApp
? Your service description myApp rest interface
? Your service version 0.0.0
? Select application type CRUD
? Object name User
? Select your application backend MongoDB
Once all the prompts are done, a new micro-service will be generated under name myApp. To see all the generated app feature, check
Note: Below information is applicable CRUD/Non-CRUD
Usually your generated project directory should like this:
|-app.js <--- Entry point of your application
|-api
| |-controllers <--- Directory for all your controllers
| | |-controller.js
| |-helpers <--- Directory for all your controllers
| | |-als.js
| | |-shortId.js
| |-services <--- Directory for all your controllers
| | |-service.js
| | |-syncService.js <--- Process you want to trigger when app starts
| |-swagger
| | |-swagger.json <--- OpenAPI Specification file
|-config <--- Directory for your config
| |-custom-environment-variables.json
| |-default.json
| |-development.json
| |-production.json
|-logger.js <--- General purpose logger file
|-package.json <--- NPM package file
|-Readme.md
|-test
| |-test.js
Here is a detailed description of most of the files
app.js This is a starting point of the application, initializing the validations and swagger UI, all of the REST API path (using /api/swagger/swagger.json)
.eslintrc.js This file contain all linting rules for this project
.prettierrc.json This file contain all Prettier rules for this project
logger.js This is a wrapper around Winston
/api/controllers/* This directory has all the controllers. These controllers are to format your request and response.
The metricController is exposing the Prometheus data via /metrics end point. If you want to see some example charts, explore the metric directory at the root level
/api/serivce/* This directory has all the services. Every rest end point has its own serivce function that can be used to add business logic or to interact with external services.
The sync service (/api/services/syncService.js) initilize the database connecton, apart from that, it can be used to start a background process.
For rest of the files, generate the app and see the application Readme
This service has out of the box support sorting, filter, projection and pagination, background tasks, Metrics
Assuming this service have name, age, address, country fields in the the schema. Then following features are available
In the get request, documents can sorted $sortBy parameter. Documents can be sorted in both ascending and descending direction. Ex: +age -name to sort the documents by age in ascending order and name is descending order.
To control what fields you can sort, go to /api/helpers/queryHooks.js and inside the mapping function modify the sortFields keys. Assuming, you want to enable name and age sorting, then the sortField in the mapping function will be like:
...
function mapping() {
return {
sortFields: ['name', 'age'],
...
Documents can be filtered using the parameter $filter by writing SQL-like statements. For example, to get all documents where the age is in ['23', '45'] and address = 'address1', the parameter $filter should be like age in ( '23', '45') and address = 'address1'.
Here one thing to note down is the quotes ('') around all the values, these quotes are always required, for every value. Right now integer, string, boolean, and date data types are supported. To add more data type support, see /api/helpers/mongoFilter.pegjs file. For more examples see filter test cases.
To control what fields you can filter, go to /api/helpers/queryHooks.js and inside the mapping function modify the queryFields keys. Assuming, you want to enable name and age filter, then the queryFields in the mapping function will be like:
...
function mapping() {
...
queryFields: [
{ name: 'name', type: 'string' },
{ name: 'age', type: 'int' }
],
...
...
Projection is a way to select only the necessary data rather than selecting every column. Use the $projection parameter to define the projection fields. Assuming you want to get only age and name out of all the available columns in the database, then the $projection parameter will be like age name. For more examples see filter test cases.
By Default applications exposes, pagination parameters $top and $skip.
To visualize and interact with the API’s resources go to "http://localhost:3000/user-service/docs"
Define your request body or request parameter in the swagger file (api/swagger/swagger.json). To know more about the definitions, see Swagger Documentation. According to the definitions defined in the swagger, all the validations will be performed.
All the application metrics like CPU usages, event lag delay, TPM, and p95 are available. For more details, see your generated application
This generator uses the config node package to manage all your external configuration. To know more, what's the use of different files in /config directory, visit the Config page
Once you run test cases (using the command npm test), a /unittest.log file will be generated. In your terminal, you will only see all passed and failed tests. To see test logs open the /unittest.log file. This file will regenerate with every test case run. If you want to see all the logs when the test runs, go to your test file /test/test.js and comment out logger('unittest.log').switchToFile();
-
Go to you swagger file
api/swagger/swagger.jsonand add new path definition, under paths add something like this"paths": { "/newPath": { "x-controller": "yourControllerFile", <---- this is a controller file name under /api/controllers "get": { "operationId": "yourFunctionName", <---- this is a function name in the yourControllerFile ... } } },To know more about the swagger path definition see official docs
-
Add controller file
yourControllerFileinapi/controllersdirectory and functionyourFunctionName.
- Out of the box swaggerUI, swagger validation, REST API
- Test cases available with 100 % coverage
- Add correlationId to every log
- Add Observability tools
- Add Cassandra DB support
- Add SSE support
Contributions are what make the open source community such an amazing place to learn, inspire, and create. Any contributions you make are greatly appreciated.
If you have a suggestion that would make this better, please fork the repo and create a pull request. You can also simply open an issue with the tag "enhancement". Don't forget to give the project a star! Thanks again!
- Fork the Project
- Create your Feature Branch (
git checkout -b feature/AmazingFeature) - Commit your Changes (
git commit -m 'Add some AmazingFeature') - Push to the Branch (
git push origin feature/AmazingFeature) - Open a Pull Request