feature/upgrde-all - updated to better file structure and added swagger ui - also added ability to version and additional middleware

Author: MMT-LD

.babelrc

@@ -4,7 +4,12 @@
       "targets": {
         "node": "current"
       },
+      "useBuiltIns": true,
       "debug": true
     }]
+  ],
+  "plugins": [
+    "transform-runtime",
+    "transform-object-rest-spread"
   ]
 }

.eslintrc.json

@@ -1,6 +1,9 @@
 {
   "parser": "babel-eslint",
-  "extends": "airbnb-base",
+  "extends": [
+    "airbnb-base",
+    "prettier"
+  ],
   "env": {
     "node": true,
     "mocha": true
@@ -13,7 +16,8 @@
     "import/no-extraneous-dependencies": 0,
     "global-require": 0,
     "radix": 0,
-    "no-param-reassign": 0
+    "no-param-reassign": 0,
+    "no-console": 0
   },
   "plugins": [
       "import"

config/default-example.json

@@ -1,6 +1,9 @@
 {
   "server": {
     "host": "localhost",
-    "port": 40001
+    "port": 40001,
+    "swagger": {
+      "enable": true
+    }
   }
 }

package.json

@@ -24,12 +24,10 @@
     "eslint": "^4.2.0",
     "eslint-config-airbnb": "^15.0.2",
     "eslint-plugin-import": "^2.7.0",
-    "eslint-plugin-jsx-a11y": "^6.0.2",
     "husky": "^0.14.3",
     "lint-staged": "^4.0.1",
     "mocha": "^3.4.2",
     "morgan": "^1.8.2",
-    "nodemon": "^1.11.0",
     "nyc": "^11.0.3",
     "prettier": "^1.5.2",
     "prettier-eslint": "^6.4.2",
@@ -39,19 +37,24 @@
   "dependencies": {
     "babel-cli": "^6.24.1",
     "babel-core": "^6.25.0",
+    "babel-plugin-transform-runtime": "^6.23.0",
     "babel-preset-env": "^1.6.0",
     "babel-preset-es2015": "^6.24.1",
     "babel-preset-stage-0": "^6.24.1",
     "body-parser": "^1.17.2",
+    "chalk": "^2.3.0",
+    "compose-middleware": "^4.0.0",
     "compression": "^1.7.0",
     "config": "^1.26.1",
     "cookie-parser": "^1.4.3",
     "cross-env": "^5.0.1",
+    "eslint-config-prettier": "^2.9.0",
     "express": "^4.15.3",
     "helmet": "^3.6.1",
     "nodemon": "^1.11.0",
     "request": "^2.81.0",
-    "rimraf": "^2.6.1"
+    "rimraf": "^2.6.1",
+    "swagger-ui-express": "^2.0.13"
   },
   "engines": {
     "node": ">=6.10.0",

src/index.js

@@ -6,8 +6,11 @@ const app = server.create();
 const { host, port } = config.get('server');
 
 routes.register(app);
+console.log(app._router.stack);
 
 app.listen(port, () => {
   console.log(`✅ 😀 - Front-End server is running at http://${host}:${port}`);
-  console.log(`Try me: http://${host}:${port}/v1/someapi/promise`);
+  console.log(
+    `Try me: http://${host}:${port}/api/v1/something or http://${host}:${port}/api/v2/something`,
+  );
 });

src/middleware/error-handler.js

@@ -0,0 +1,18 @@
+// eslint-disable-next-line no-unused-vars
+const errorHandler = (err, req, res, next) => {
+  const status = err.status || 500;
+  return res.status(status).send({
+    status,
+    error: err.message || 'Something failed!',
+  });
+};
+
+const invalidEndpoint = (req, res, next) => {
+  const error = new Error(
+    'Ooops... It looks like this query or endpoint is incorrect/invalid',
+  );
+  error.status = 404;
+  return next(error);
+};
+
+export { errorHandler, invalidEndpoint };

src/middleware/examples.js

@@ -0,0 +1,19 @@
+const example = (req, res, next) => {
+  // Example middleware to add a property to all routes
+  req.example = 'example';
+  console.log(
+    `THIS MIDDLEWARE APPLIES TO ALL ROUTES - Example - added global param ${
+      req.example
+    }`,
+  );
+  return next();
+};
+
+const example1 = (req, res, next) => {
+  console.log(
+    `THIS MIDDLEWARE APPLIES TO ALL ROUTES - Example1 - Time: ${Date.now()}`,
+  );
+  return next();
+};
+
+export { example, example1 };

src/middleware/index.js

@@ -1,7 +1,4 @@
-export default {
-  example(req, res, next) {
-    // Example middleware to add a property to all routes
-    req.example = 'example';
-    return next();
-  },
-};
+import { example, example1 } from './examples';
+import { errorHandler, invalidEndpoint } from './error-handler';
+
+export { example, example1, errorHandler, invalidEndpoint };

src/routes/index.js

@@ -0,0 +1,10 @@
+import express from 'express';
+import v1Routes from './v1';
+import v2Routes from './v2';
+
+const router = express.Router();
+
+router.use('/v1', v1Routes);
+router.use('/v2', v2Routes);
+
+export default router;

src/routes/v1/index.js

@@ -0,0 +1,15 @@
+import express from 'express';
+
+const router = express.Router();
+
+router.use((req, res, next) => {
+  console.log('THIS MIDDLEWARE WILL ONLY APPLY TO THIS ROUTERS ROUTE V1');
+  return next();
+});
+
+router.get('/something', (req, res, next) => {
+  const error = new Error('An error occurred');
+  return next(error);
+});
+
+export default router;

src/routes/v2/index.js

@@ -0,0 +1,12 @@
+import express from 'express';
+
+const router = express.Router();
+
+router.use((req, res, next) => {
+  console.log('THIS MIDDLEWARE WILL ONLY APPLY TO THIS ROUTERS ROUTE V2');
+  return next();
+});
+
+router.get('/something', (req, res) => res.status(200).send({ success: true }));
+
+export default router;

src/service/routes.js

@@ -1,11 +1,16 @@
-import routes from '../routes/example';
+import routes from '../routes';
+import { errorHandler, invalidEndpoint } from '../middleware';
 
 export default {
   register(app) {
     // Prevent 404 when locating favicon
     app.get('/favicon.ico', (req, res) => res.sendStatus(204));
-    app.get('/v1/someapi/async', routes.asyncExample);
-    app.get('/v1/someapi/promise', routes.promiseExample);
-    app.post('/v1/someapi/example', routes.asyncExample);
+    // All routes start with api
+    // Then split off into versions inside routes
+    app.use('/api', routes);
+    // Check for invalid endpoint
+    app.use(invalidEndpoint);
+    // Error handler - must be last to pick up errors
+    app.use(errorHandler);
   },
 };

src/service/server.js

@@ -4,22 +4,32 @@ import cookieParser from 'cookie-parser';
 import express from 'express';
 import helmet from 'helmet';
 import morgan from 'morgan';
+import config from 'config';
+import swaggerSetup from './swagger';
 
-import middleware from '../middleware';
+// Middleware - error handler must go inside routes as this needs
+// to be the last app.use and applied after routes is defined
+import { example, example1 } from '../middleware';
 
 const app = express();
 
 app.use(helmet());
 app.use(bodyParser.urlencoded({ extended: true }));
 app.use(bodyParser.json());
 app.use(cookieParser());
+
 // Middleware applied to all routes
-app.use(middleware.example);
+app.use(example, example1);
 app.use(compression());
 
 // use morgan to log requests to the console
 app.use(morgan('dev'));
 
+// If swagger is enabled then load in config etc
+if (config.get('server.swagger.enable')) {
+  app.use('/docs', swaggerSetup(app));
+}
+
 export default {
   create() {
     return app;

src/service/swagger.js

@@ -0,0 +1,44 @@
+import { serve, setup } from 'swagger-ui-express';
+import { compose } from 'compose-middleware';
+import fs from 'fs';
+import path from 'path';
+import chalk from 'chalk';
+
+const retrieveSwaggerDocument = filename => {
+  const location = path.join(process.cwd(), filename || 'swagger.json');
+
+  return new Promise((resolve, reject) =>
+    fs.readFile(location, (err, data) => {
+      if (err)
+        return reject(
+          `Oooops... It seems we cannot locate a swagger.json file - this should be in the root of your project.`,
+        );
+      return resolve(JSON.parse(data));
+    }),
+  );
+};
+
+function swaggerSetup(app, showExplorer = true, doc = null, options = {}) {
+  return async (req, res, next) => {
+    try {
+      const document = await retrieveSwaggerDocument(doc);
+
+      return compose([
+        serve,
+        setup(document, showExplorer, {
+          validatorUrl: null,
+          docExpansion: 'list',
+          ...options,
+        }),
+      ])(req, res, next);
+    } catch (error) {
+      console.log(chalk.red(error));
+      return next({
+        status: 404,
+        message: error,
+      });
+    }
+  };
+}
+
+export default swaggerSetup;

swagger.json

@@ -0,0 +1,47 @@
+{
+  "swagger": "2.0",
+  "basePath": "/api",
+  "info": {
+    "title": "API Boilerplate - example swagger document",
+    "version": "v2"
+  },
+  "paths": {
+    "/v1/something": {
+      "get": {
+        "operationId": "listVersionsv2",
+        "summary": "Example error on V1 route",
+        "produces": [
+          "application/json"
+        ],
+        "tags": [
+          "v1"
+        ],
+        "responses": {
+          "500": {
+            "description": "500 response"
+          }
+        }
+      }
+    },
+    "/v2/something": {
+      "get": {
+        "operationId": "getVersionDetailsv2",
+        "summary": "Example success on v2 route",
+        "produces": [
+          "application/json"
+        ],
+        "tags": [
+          "v2"
+        ],
+        "responses": {
+          "200": {
+            "description": "200 response"
+          }
+        }
+      }
+    }
+  },
+  "consumes": [
+    "application/json"
+  ]
+}