Support for referencing external json schemas

Author: Deadarius

src/DefinitionGenerator.ts

@@ -1,10 +1,11 @@
-import { JSONSchema7 } from 'json-schema';
 // tslint:disable-next-line no-submodule-imports
 import { validateSync as openApiValidatorSync } from 'swagger2openapi/validate';
 import * as uuid from 'uuid';
 
 import { IDefinition, IDefinitionConfig, IOperation, IParameterConfig, IServerlessFunctionConfig } from './types';
-import { clone, isIterable, merge, omit } from './utils';
+import { cleanSchema } from './utils';
+import { parseModels } from './SchemaBuilder';
+import _ = require('lodash');
 
 export class DefinitionGenerator {
   // The OpenAPI version we currently validate against
@@ -18,23 +19,25 @@ export class DefinitionGenerator {
 
   public config: IDefinitionConfig;
 
+  private root: string;
+
   /**
    * Constructor
-   * @param serviceDescriptor IServiceDescription
    */
-  constructor (config: IDefinitionConfig) {
-    this.config = clone(config);
+  constructor (config: IDefinitionConfig, root: string) {
+    this.config = _.cloneDeep(config);
+    this.root = root;
   }
 
-  public parse () {
+  public async parse () {
     const {
       title = '',
       description = '',
       version = uuid.v4(),
       models,
     } = this.config;
 
-    merge(this.definition, {
+    _.merge(this.definition, {
       openapi: this.version,
       info: { title, description, version },
       paths: {},
@@ -44,24 +47,7 @@ export class DefinitionGenerator {
       },
     });
 
-    if (isIterable(models)) {
-      for (const model of models) {
-        if (!model.schema) {
-          continue;
-        }
-
-        for (const definitionName of Object.keys(model.schema.definitions || {})) {
-          const definition = model.schema.definitions[definitionName];
-          if (typeof definition !== 'boolean') {
-            this.definition.components.schemas[definitionName] = this.cleanSchema(this.updateReferences(definition));
-          }
-        }
-
-        const schemaWithoutDefinitions = omit(model.schema, ['definitions']);
-
-        this.definition.components.schemas[model.name] = this.cleanSchema(this.updateReferences(schemaWithoutDefinitions));
-      }
-    }
+    this.definition.components.schemas = await parseModels(models, this.root);
 
     return this;
   }
@@ -101,49 +87,10 @@ export class DefinitionGenerator {
           };
 
           // merge path configuration into main configuration
-          merge(this.definition.paths, pathConfig);
-        }
-      }
-    }
-  }
-
-  /**
-   * Cleans schema objects to make them OpenAPI compatible
-   * @param schema JSON Schema Object
-   */
-  private cleanSchema (schema) {
-    // Clone the schema for manipulation
-    const cleanedSchema = clone(schema);
-
-    // Strip $schema from schemas
-    if (cleanedSchema.$schema) {
-      delete cleanedSchema.$schema;
-    }
-
-    // Return the cleaned schema
-    return cleanedSchema;
-  }
-
-  /**
-   * Walks through the schema object recursively and updates references to point to openapi's components
-   * @param schema JSON Schema Object
-   */
-  private updateReferences (schema: JSONSchema7): JSONSchema7 {
-    const cloned = clone(schema);
-
-    if (cloned.$ref) {
-      cloned.$ref = cloned.$ref.replace('#/definitions', '#/components/schemas');
-    } else {
-      for (const key of Object.getOwnPropertyNames(cloned)) {
-        const value = cloned[key];
-
-        if (typeof value === 'object') {
-          cloned[key] = this.updateReferences(value);
+          _.merge(this.definition.paths, pathConfig);
         }
       }
     }
-
-    return cloned;
   }
 
   /**
@@ -240,7 +187,7 @@ export class DefinitionGenerator {
         }
 
         if (parameter.schema) {
-          parameterConfig.schema = this.cleanSchema(parameter.schema);
+          parameterConfig.schema = cleanSchema(parameter.schema);
         }
 
         if (parameter.example) {
@@ -299,7 +246,7 @@ export class DefinitionGenerator {
             reqBodyConfig.description = documentationConfig.requestBody.description;
           }
 
-          merge(requestBodies, reqBodyConfig);
+          _.merge(requestBodies, reqBodyConfig);
         }
       }
     }
@@ -309,9 +256,9 @@ export class DefinitionGenerator {
 
   private attachExamples (target, config) {
     if (target.examples && Array.isArray(target.examples)) {
-      merge(config, { examples: clone(target.examples) });
+      _.merge(config, { examples: _.cloneDeep(target.examples) });
     } else if (target.example) {
-      merge(config, { example: clone(target.example) });
+      _.merge(config, { example: _.cloneDeep(target.example) });
     }
   }
 
@@ -339,12 +286,12 @@ export class DefinitionGenerator {
               description: header.description || `${header.name} header`,
             };
             if (header.schema) {
-              methodResponseConfig.headers[header.name].schema = this.cleanSchema(header.schema);
+              methodResponseConfig.headers[header.name].schema = cleanSchema(header.schema);
             }
           }
         }
 
-        merge(responses, {
+        _.merge(responses, {
           [response.statusCode]: methodResponseConfig,
         });
       }
@@ -370,7 +317,7 @@ export class DefinitionGenerator {
 
         this.attachExamples(responseModel, resModelConfig);
 
-        merge(content, { [responseKey] : resModelConfig });
+        _.merge(content, { [responseKey] : resModelConfig });
       }
     }
 

src/ServerlessOpenApiDocumentation.ts

@@ -1,11 +1,11 @@
-import chalk from 'chalk';
+import * as chalk from 'chalk';
 import * as fs from 'fs';
 import * as YAML from 'js-yaml';
 import { inspect } from 'util';
 import { DefinitionGenerator } from './DefinitionGenerator';
 import { IDefinitionType, ILog, Format, IDefinitionConfig } from './types';
-import { merge } from './utils';
 import * as Serverless from 'serverless';
+import _ = require('lodash');
 
 interface Options {
   indent: number,
@@ -127,17 +127,17 @@ export class ServerlessOpenApiDocumentation {
   /**
    * Generates OpenAPI Documentation based on serverless configuration and functions
    */
-  private generate () {
+  public async generate () {
     this.log(chalk.bold.underline('OpenAPI v3 Documentation Generator\n\n'));
     // Instantiate DocumentGenerator
-    const generator = new DefinitionGenerator(this.customVars.documentation);
+    const generator = new DefinitionGenerator(this.customVars.documentation, this.serverless.config.servicePath);
 
-    generator.parse();
+    await generator.parse();
 
     // Map function configurations
     const funcConfigs = this.serverless.service.getAllFunctions().map((functionName) => {
       const func = this.serverless.service.getFunction(functionName);
-      return merge({ _functionName: functionName }, func);
+      return _.merge({ _functionName: functionName }, func);
     });
 
     // Add Paths to OpenAPI Output from Function Configuration

src/parse.ts

@@ -0,0 +1,63 @@
+import * as path from 'path';
+import * as _ from 'lodash';
+import { JSONSchema7 } from 'json-schema';
+
+import * as $RefParser from 'json-schema-ref-parser';
+
+import { IModel } from './types';
+import { cleanSchema } from './utils';
+
+export async function parseModels(models: IModel[], root: string): Promise<{}> {
+  const schemas = {};
+
+  if (!_.isArrayLike(models)) {
+    throw new Error('Empty models');
+  }
+
+  for (const model of models) {
+    if (!model.schema) {
+      continue;
+    }
+
+    if (typeof model.schema === 'string') {
+      const fullPath = path.resolve(root, model.schema);
+
+      const schema = await $RefParser.bundle(fullPath) as JSONSchema7;
+
+      _.assign(schemas, updateReferences(schema.definitions));
+
+      schemas[model.name] = updateReferences(cleanSchema(schema));
+    }
+
+    if(typeof model.schema === 'object') {
+      schemas[model.name] = updateReferences(cleanSchema(model.schema));
+    }
+  }
+
+  return schemas;
+}
+
+function updateReferences (schema: JSONSchema7): JSONSchema7 {
+  if(!schema) {
+    return schema;
+  }
+
+  const cloned = _.cloneDeep(schema) as JSONSchema7;
+
+  if (cloned.$ref) {
+    return {
+      ...cloned,
+      $ref: cloned.$ref.replace('#/definitions', '#/components/schemas')
+    };
+  }
+
+  for (const key of Object.getOwnPropertyNames(cloned)) {
+    const value = cloned[key];
+
+    if (typeof value === 'object') {
+      cloned[key] = updateReferences(value);
+    }
+  }
+
+  return cloned;
+}

src/types.ts

@@ -1,10 +1,8 @@
-import { JSONSchema7 } from 'json-schema';
-
-export interface IModels {
+export interface IModel {
   name: string;
   description: string;
   contentType: string;
-  schema: JSONSchema7;
+  schema: string;
   examples: any[];
   example: object;
 }
@@ -13,7 +11,7 @@ export interface IDefinitionConfig {
   title: string;
   description: string;
   version?: string;
-  models: IModels[];
+  models: IModel[];
 }
 
 export enum Format {

src/utils.ts

@@ -1,22 +1,4 @@
-import { Clone, IMerge, Merge } from 'lutils';
 
-export const merge: IMerge = new Merge({ depth: 100 }).merge;
-export const clone = new Clone({ depth: 100 }).clone;
+import _ = require('lodash');
 
-export function isIterable (obj) {
-  if (obj === null || obj === undefined) {
-    return false;
-  }
-
-  return typeof obj[Symbol.iterator] === 'function';
-}
-
-export function omit<T extends object> (obj: T, keys: string[]): T {
-  const cloned = clone(obj);
-
-  for (const key of keys) {
-    delete cloned[key];
-  }
-
-  return cloned;
-}
+export const cleanSchema = schema => _.omit(schema, '$schema', 'definitions')