Initial OpenAPI module

Author: stephenbaldwin

IMountableItem.ts

@@ -0,0 +1,20 @@
+import Router from './Router';
+import express from 'express';
+
+export default interface IMountableItem {
+  path: string;
+  httpMethod: string;
+
+  at: (path: string) => this;
+
+  asExpressRoute: () => (req: express.Request, res: express.Response) => void;
+  asKoaRoute: () => void;
+  asMetal: () => void;
+
+  withOptions: (options: any) => this;
+  setRouter: (router: Router) => this
+}
+
+export interface IMountableItemClass {
+  new (options: any, router?: Router): IMountableItem;
+}

OpenApi.ts

@@ -0,0 +1,150 @@
+import IMountableItem from './IMountableItem';
+import Router from './Router';
+import Route, { IOperationVariable } from './Route';
+import express from 'express';
+
+interface IParameter {
+  name: string;
+  required: boolean;
+  in: string;
+  type: string;
+  default?: string | boolean | number;
+}
+
+interface IBuildParametersArguments {
+  variableDefinitions: IOperationVariable[];
+  variableLocation: string;
+}
+
+const PATH_VARIABLES_REGEX = /:([A-Za-z]+)/g
+
+function openApiPath(path: string): string {
+  return path.replace(PATH_VARIABLES_REGEX, '{$1}');
+}
+
+// TODO: Return Type and Attempt to get description from graphql
+function buildParametersArray({ variableDefinitions, variableLocation }: IBuildParametersArguments): IParameter[] {
+  return variableDefinitions.map(
+    (variableDefinition: IOperationVariable): IParameter => ({
+      name: variableDefinition.name,
+      required: variableDefinition.required,
+      default: variableDefinition.defaultValue,
+      in: variableLocation,
+      type: variableDefinition.type,
+    })
+  );
+}
+
+export class V2 implements IMountableItem {
+  public path: string = '/docs/openapi/v2';
+  public httpMethod: string = 'get';
+
+  constructor(options: any, private router?: Router) {
+  }
+
+  setRouter(router: Router): this {
+    this.router = router;
+
+    return this;
+  }
+
+  at(path: string): this {
+    this.path = path;
+
+    return this;
+  }
+
+  private generateDocumentation(): any {
+    const { router } = this;
+
+    if (!router) {
+      throw new Error(`
+        Router must be set in order to generate documentation. If you are using router.mount(), the router will automatically be set.
+        If you are using this outside of a Router instance, please leverage #setRouter() to select a class that adheres to the router
+        interface.
+      `);
+    }
+
+    const page: any = {
+      swagger: '2.0',
+      info: {},
+      paths: {},
+    };
+
+    router.routes.forEach((route) => {
+      const { path, httpMethod } = route;
+
+      const docPath = openApiPath(path);
+
+      if (!page.paths[docPath]) {
+        page.paths[docPath] = {};
+      }
+
+      const routeDoc: any = page.paths[docPath][httpMethod] = {};
+
+      routeDoc.parameters = [];
+      routeDoc.consumes = [];
+      routeDoc.produces = ['application/json'];
+      routeDoc.responses = {
+        200: {
+          description: 'Server alive. This does not mean that the query was completed succesfully. Check the errors object in the response',
+        },
+        400: {
+          description: 'Authentication Required',
+        },
+        500: {
+          description: 'Server error.',
+        }
+      };
+
+      if (httpMethod === 'post') {
+        routeDoc.consumes.push('application/json');
+      }
+
+      routeDoc.parameters.push(
+        ...buildParametersArray({
+          variableDefinitions: route.queryVariables,
+          variableLocation: 'query'
+        })
+      );
+
+      routeDoc.parameters.push(
+        ...buildParametersArray({
+          variableDefinitions: route.pathVariables,
+          variableLocation: 'path'
+        })
+      );
+
+      routeDoc.parameters.push(
+        ...buildParametersArray({
+          variableDefinitions: route.bodyVariables,
+          variableLocation: 'body'
+        })
+      );
+    });
+
+    return page;
+  }
+
+  withOptions(options: {}): this {
+    return this;
+  }
+
+  asExpressRoute(): (req: express.Request, res: express.Response) => void {
+    const doc = this.generateDocumentation();
+
+    return (req: express.Request, res: express.Response) => {
+      res
+        .status(200)
+        .json(doc);
+    }
+  }
+
+  asKoaRoute() {
+    throw new Error('not yet implemented');
+  }
+
+  asMetal() {
+    throw new Error('not yet implemented');
+  }
+}

Route.ts

@@ -1,11 +1,15 @@
+import IMountableItem from './IMountableItem';
+import Router from './Router';
 import { DocumentNode, parse, print, getOperationAST } from 'graphql';
 import { AxiosTransformer, AxiosInstance, AxiosRequestConfig } from 'axios';
 import * as express from 'express';
 
+const PATH_VARIABLES_REGEX = /:([A-Za-z]+)/g
+
 export interface IConstructorRouteOptions {
   schema: DocumentNode | string; // GraphQL Document Type
   operationName: string;
-
+  axios: AxiosInstance;
   path?: string;
   cacheTimeInMs?: number;
   method?: string;
@@ -23,13 +27,14 @@ export interface IRouteOptions {
   defaultVariables?: {};
 }
 
-interface IOperationVariable {
+export interface IOperationVariable {
   name: string;
   required: boolean;
+  type: string;
   defaultValue?: string | boolean | number;
 }
 
-interface IResponse {
+export interface IResponse {
   statusCode: number;
   body: {};
 }
@@ -42,6 +47,23 @@ enum EHTTPMethod {
 }
 */
 
+function translateVariableType(node: any): any {
+  if (node.type.kind === 'NonNullType') {
+    return translateVariableType(node.type);
+  }
+
+  switch (node.type.name.value) {
+    case 'Int':
+      return 'number';
+    case 'Boolean':
+      return 'boolean';
+    case 'String':
+    default:
+      return 'string';
+
+  }
+}
+
 function cleanPath(path: string): string {
   if (path[0] === '/') {
     return path;
@@ -50,7 +72,7 @@ function cleanPath(path: string): string {
   return `/${path}`;
 }
 
-export default class Route {
+export default class Route implements IMountableItem {
   public path!: string;
   public httpMethod: string = 'get';
 
@@ -62,6 +84,7 @@ export default class Route {
   // the change
   private configurationIsFrozen: boolean = false;
 
+  private axios!: AxiosInstance;
   private schema!: DocumentNode;
 
   private operationName!: string;
@@ -75,7 +98,7 @@ export default class Route {
 
   private cacheTimeInMs: number = 0;
 
-  constructor(configuration: IConstructorRouteOptions, private axios: AxiosInstance) {
+  constructor(configuration: IConstructorRouteOptions, private router?: Router) {
     this.configureRoute(configuration);
   }
 
@@ -90,6 +113,7 @@ export default class Route {
     }
 
     this.schema = typeof schema === 'string' ? parse(schema) : schema;
+    this.axios = configuration.axios;
 
     this.setOperationName(operationName);
 
@@ -100,6 +124,12 @@ export default class Route {
     this.withOptions(options);
   }
 
+  setRouter(router: Router): this {
+    this.router = router;
+
+    return this;
+  }
+
   at(path: string): this {
     this.path = cleanPath(path);
 
@@ -118,6 +148,7 @@ export default class Route {
       (node: any): IOperationVariable => ({
         name: node.variable.name.value,
         required: node.type.kind === 'NonNullType',
+        type: translateVariableType(node),
         defaultValue: node.defaultValue,
       })
     );
@@ -235,6 +266,10 @@ export default class Route {
     throw new Error('Not available! Submit PR');
   }
 
+  asMetal() {
+    throw new Error('Not available! Submit PR');
+  }
+
   // areVariablesValid(variables: {}) {}
 
   transformRequest(fn: AxiosTransformer): this {
@@ -255,6 +290,45 @@ export default class Route {
     return this;
   }
 
+  get queryVariables(): IOperationVariable[] {
+    if (this.httpMethod === 'post') {
+      return [];
+    }
+
+    return this.nonPathVariables;
+  }
+
+  get bodyVariables(): IOperationVariable[] {
+    if (this.httpMethod === 'get') {
+      return [];
+    }
+
+    return this.nonPathVariables;
+  }
+
+  get pathVariables(): IOperationVariable[] {
+    const matches = this.path.match(PATH_VARIABLES_REGEX);
+
+    if (!matches) {
+      return [];
+    }
+
+    const pathVariableNames = matches.map(match => match.substr(1));
+
+    return this.operationVariables.filter(
+      ({ name }) => pathVariableNames.includes(name)
+    );
+  }
+
+  get nonPathVariables(): IOperationVariable[] {
+    const pathVariableNames = this.pathVariables.map(({ name }) => name);
+
+    return this.operationVariables
+      .filter(
+        ({ name }) => !pathVariableNames.includes(name)
+      );
+  }
+
   private async makeRequest(variables: {}): Promise<IResponse> {
     const { axios, schema, operationName } = this;