Added OpenAPI definition and Swagger UI

Author: YegorMedvedev

package.json

@@ -8,6 +8,7 @@
   "scripts": {
     "prebuild": "rm -rf ./build",
     "build": "tsc",
+    "postbuild": "mkdir -p build/api/schemas && find src/ -type f -name '*.yaml' -exec cp '{}' build/api/schemas/ ';'",
     "start": "node build/main.js",
     "lint": "tslint './{src,test}/**/*.ts'",
     "lint:fix": "yarn lint --fix",
@@ -26,6 +27,8 @@
     "multer": "1.4.2",
     "pg": "8.2.1",
     "reflect-metadata": "0.1.13",
+    "swagger-jsdoc": "4.0.0",
+    "swagger-ui-express": "4.1.4",
     "uuid": "8.0.0",
     "winston": "3.2.1"
   },
@@ -36,6 +39,8 @@
     "@types/mongodb": "3.5.18",
     "@types/multer": "1.4.3",
     "@types/nock": "11.1.0",
+    "@types/swagger-jsdoc": "3.0.2",
+    "@types/swagger-ui-express": "4.1.2",
     "@types/uuid": "7.0.3",
     "@types/winston": "2.4.4",
     "casual": "1.6.2",

src/api/controllers/application-controller/application-controller.ts

@@ -1,15 +1,56 @@
 import {BaseHttpController, controller, httpGet} from "inversify-express-utils";
+import * as swaggerUi from "swagger-ui-express";
 
+import {getSwaggerSpecification} from "../../../infrastructure/utils/swagger-specification";
 import {HealthService} from "../../../services/health-service/health-service";
 
+import {HttpMethodSync} from "./types";
+
 @controller("/Application")
 export class ApplicationController extends BaseHttpController {
   constructor(private readonly healthService: HealthService) {
     super();
   }
 
+  /**
+   * @swagger
+   *  /Application/Health:
+   *  get:
+   *    tags:
+   *      - Application
+   *    summary: "Application Health"
+   *    description: "Returns general information regarding application health"
+   *    operationId: "applicationHealth"
+   *    responses:
+   *      200:
+   *        description: "Health details retrieved"
+   *        content:
+   *          application/json:
+   *            schema:
+   *              $ref: '#/components/schemas/ApplicationHealthDto'
+   */
   @httpGet("/Health")
-  public async getStatus() {
+  public async getHealth() {
     return this.healthService.getHealth();
   }
+
+  /**
+   * @swagger
+   *  /Application/Docs:
+   *  get:
+   *    tags:
+   *      - Application
+   *    summary: "Application Swagger Documentation"
+   *    description: "Returns Swagger UI"
+   *    operationId: "applicationDocs"
+   *    responses:
+   *      200:
+   *        description: "Swagger UI"
+   */
+  @httpGet("/Docs")
+  public async getApiDocumentation() {
+    const swaggerSpecification = await getSwaggerSpecification();
+    const setup = swaggerUi.setup(swaggerSpecification, {explorer: true}) as HttpMethodSync;
+    setup(this.httpContext.request, this.httpContext.response);
+  }
 }

src/api/controllers/application-controller/schemas/health-schema.yaml

@@ -0,0 +1,58 @@
+components:
+  schemas:
+    ApplicationHealthDto:
+      type: object
+      properties:
+        node:
+          type: string
+          example: "12.11.0"
+        version:
+          type: string
+          example: "1.2.0"
+        name:
+          type: string
+          example: "node-onion-scaffold"
+        environment:
+          type: object
+          properties:
+            NODE_ENV:
+              type: string
+              example: "local"
+            PORT:
+              type: string
+              example: "4000"
+        memory:
+          type: object
+          properties:
+            rss:
+              type: string
+              example: "10 MB"
+            heapTotal:
+              type: string
+              example: "5 MB"
+            heapUsed:
+              type: string
+              example: "19.1 MB"
+            external:
+              type: string
+              example: "22.2 MB"
+        storage:
+          type: object
+          properties:
+            mongodb:
+              type: object
+              properties:
+                status:
+                  type: string
+                  example: "ok"
+                details:
+                  type: string;
+            postgres:
+              type: object
+              properties:
+                status:
+                  type: string
+                  example: "error"
+                details:
+                  type: string;
+                  example: "DatabaseConnectionError"

src/api/controllers/application-controller/types.ts

@@ -0,0 +1,3 @@
+import {Request, Response} from "express";
+
+export type HttpMethodSync = (req: Request, res: Response) => Response;

src/api/middlewares/index.ts

@@ -1,2 +1,3 @@
 export * from "./error-handler";
 export * from "./correlation-id";
+export * from "./swagger-ui-server-middleware";

src/api/middlewares/swagger-ui-server-middleware.ts

@@ -0,0 +1,3 @@
+import * as swaggerUi from "swagger-ui-express";
+
+export const SwaggerUiServeMiddleware = swaggerUi.serve;

src/infrastructure/utils/swagger-specification.ts

@@ -0,0 +1,42 @@
+import * as swaggerJSDoc from "swagger-jsdoc";
+
+import {getPackageJson} from "../config";
+
+const getOptions = () => {
+  const packageJsonDetails = getPackageJson();
+  const version = packageJsonDetails.version.split("#")[0];
+
+  return {
+    definition: {
+      openapi: "3.0.2",
+      info: {
+        version,
+        title: packageJsonDetails.name,
+      },
+      schemas: {},
+    },
+    apis: ["**/api/controllers/**/*/*.ts", "**/api/controllers/**/*/*.js", "**/api/**/*/*.yaml"],
+  };
+};
+
+/**
+ * @description
+ * Use closure principle here in order to reduce Swagger specification build time
+ * It takes ages and depends on amount of methods in /api/http
+ */
+let swaggerJsDocObject: Record<string, any> | undefined;
+
+export const getSwaggerSpecification = (): Promise<Record<string, any>> => {
+  if (swaggerJsDocObject != null) {
+    return Promise.resolve(swaggerJsDocObject);
+  }
+
+  return new Promise((resolve, reject) => {
+    try {
+      swaggerJsDocObject = swaggerJSDoc(getOptions());
+      resolve(swaggerJsDocObject);
+    } catch (e) {
+      reject(e);
+    }
+  });
+};

src/main.ts

@@ -9,7 +9,7 @@ import {InversifyExpressServer} from "inversify-express-utils";
 
 import {container, getPort, Logger, setProcessListeners} from "./infrastructure";
 import "./infrastructure/config/config";
-import {CorrelationId, ErrorHandler} from "./api";
+import {CorrelationId, ErrorHandler, SwaggerUiServeMiddleware} from "./api";
 
 setProcessListeners();
 
@@ -23,6 +23,7 @@ new InversifyExpressServer(container)
     app.use(json());
     app.use(compression());
     app.use(CorrelationId);
+    app.use("/Application/Docs", SwaggerUiServeMiddleware);
   })
   .setErrorConfig((app: Application) => {
     app.use(ErrorHandler);

tsconfig.json

@@ -2,7 +2,7 @@
   "compilerOptions": {
     "module": "commonjs",
     "declaration": true,
-    "removeComments": true,
+    "removeComments": false,
     "emitDecoratorMetadata": true,
     "experimentalDecorators": true,
     "target": "es2017",