Introspect GraphQL endpoint for variable definitions

Author: stephenbaldwin

OpenApi.ts

@@ -1,16 +1,37 @@
 import IMountableItem from './IMountableItem';
+import describeRouteVariables from './describeRouteVariables';
 import Router from './Router';
 import Route, { IOperationVariable } from './Route';
 import express from 'express';
 
+interface IOpenApiOptions {
+  title: string;
+  version: string;
+  termsOfService?: string;
+  license?: string;
+  basePath?: string;
+  host?: string;
+}
+
 interface IParameter {
   name: string;
   required: boolean;
   in: string;
-  type: string;
+  type?: string;
+  schema?: IParameterArraySchema | IParameterItemTypeOrRef;
   default?: string | boolean | number;
 }
 
+interface IParameterArraySchema {
+  type: string;
+  items: IParameterItemTypeOrRef;
+}
+
+interface IParameterItemTypeOrRef {
+  type?: string;
+  $ref?: string;
+}
+
 interface IBuildParametersArguments {
   variableDefinitions: IOperationVariable[];
   variableLocation: string;
@@ -22,24 +43,55 @@ function openApiPath(path: string): string {
   return path.replace(PATH_VARIABLES_REGEX, '{$1}');
 }
 
+function resolveRefOrType(variableType: string): IParameterItemTypeOrRef {
+  switch (variableType) {
+    case 'String':
+      return { type: 'string' };
+    case 'Boolean':
+      return { type: 'boolean' };
+    case 'Int':
+      return { type: 'number' };
+    default:
+      return { '$ref': `#/definitions/${variableType}` };
+  }
+}
+
 // 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,
-    })
+    (variableDefinition: IOperationVariable): IParameter => {
+      const parameter: IParameter = {
+        name: variableDefinition.name,
+        required: variableDefinition.required,
+        default: variableDefinition.defaultValue,
+        in: variableLocation,
+      };
+
+      if (variableDefinition.array) {
+        parameter.schema = {
+          type: 'array',
+          items: resolveRefOrType(variableDefinition.type),
+        };
+      } else {
+        const refOrType = resolveRefOrType(variableDefinition.type);
+        
+        if (refOrType.type) {
+          parameter.type = refOrType.type;
+        } else {
+          parameter.schema = refOrType;
+        }
+      }
+
+      return parameter;
+    }
   );
 }
 
 export class V2 implements IMountableItem {
   public path: string = '/docs/openapi/v2';
   public httpMethod: string = 'get';
 
-  constructor(options: any, private router?: Router) {
+  constructor(private options: IOpenApiOptions, private router?: Router) {
   }
 
   setRouter(router: Router): this {
@@ -54,7 +106,7 @@ export class V2 implements IMountableItem {
     return this;
   }
 
-  private generateDocumentation(): any {
+  private async generateDocumentation(): Promise<any> {
     const { router } = this;
 
     if (!router) {
@@ -65,78 +117,157 @@ export class V2 implements IMountableItem {
       `);
     }
 
-    const page: any = {
-      swagger: '2.0',
-      info: {},
-      paths: {},
-    };
+    try {
+      const {
+        title,
+        version,
+        termsOfService,
+        license,
+        host,
+        basePath,
+      } = this.options;
 
-    router.routes.forEach((route) => {
-      const { path, httpMethod } = route;
+      const page: any = {
+        swagger: '2.0',
+        info: {},
+        paths: {},
+        produces: ['application/json'],
+        definitions: {},
+      };
 
-      const docPath = openApiPath(path);
+      page.info.title = title;
+      page.info.version = version;
 
-      if (!page.paths[docPath]) {
-        page.paths[docPath] = {};
+      if (termsOfService) {
+        page.info.termsOfService = termsOfService;
       }
 
-      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 (license) {
+        page.info.license = { name: license };
+      }
 
-      if (httpMethod === 'post') {
-        routeDoc.consumes.push('application/json');
+      if (host) {
+        page.host = host;
       }
 
-      routeDoc.parameters.push(
-        ...buildParametersArray({
-          variableDefinitions: route.queryVariables,
-          variableLocation: 'query'
-        })
-      );
+      if (basePath) {
+        page.basePath = basePath;
+      }
 
-      routeDoc.parameters.push(
-        ...buildParametersArray({
-          variableDefinitions: route.pathVariables,
-          variableLocation: 'path'
-        })
-      );
+      router.routes.forEach((route) => {
+        const { path, httpMethod } = route;
 
-      routeDoc.parameters.push(
-        ...buildParametersArray({
-          variableDefinitions: route.bodyVariables,
-          variableLocation: 'body'
-        })
-      );
-    });
+        const docPath = openApiPath(path);
 
-    return page;
+        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');
+        }
+
+        // TODO: 'push in parameters for header'
+
+        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'
+          })
+        );
+      });
+
+      const introspectedVariableDefinitions: any = await describeRouteVariables(router);
+
+      Object.keys(introspectedVariableDefinitions).forEach((variableName) => {
+        const variableDefinition: any = introspectedVariableDefinitions[variableName];
+
+        const definitionDoc: any = page.definitions[variableName] = {};
+
+        if (variableDefinition.kind === 'INPUT_OBJECT') {
+          definitionDoc.type = 'object';
+          definitionDoc.properties = {};
+
+          variableDefinition.inputFields.forEach((field: any) => {
+            const inputDoc: any = definitionDoc.properties[field.name] = {};
+
+            inputDoc.type = 'string';
+            inputDoc.description = field.type.description;
+
+            if (field.type.kind === 'ENUM') {
+              inputDoc.enum = [];
+
+              field.type.enumValues.forEach((enumValue: any) => {
+                inputDoc.enum.push(enumValue.name);
+              });
+            }
+          });
+        }
+
+        if (variableDefinition.kind === 'ENUM') {
+          definitionDoc.type = 'string';
+          definitionDoc.enum = [];
+
+          variableDefinition.enumValues.forEach((enumValue: any) => {
+            definitionDoc.enum.push(enumValue.name);
+          });
+        }
+      });
+
+      return page;
+    } catch (error) {
+      return {
+        error: error.message,
+      };
+    }
   }
 
   withOptions(options: {}): this {
     return this;
   }
 
   asExpressRoute(): (req: express.Request, res: express.Response) => void {
-    const doc = this.generateDocumentation();
+    const generateDoc = this.generateDocumentation();
 
     return (req: express.Request, res: express.Response) => {
-      res
-        .status(200)
-        .json(doc);
+      generateDoc.then(
+        (doc) => {
+          res
+            .status(200)
+            .json(doc);
+        }
+      );
     }
   }