Wip

Author: nfour

src/DocumentGenerator.ts src/DefinitionGenerator.tssrc/DocumentGenerator.ts renamed to src/DefinitionGenerator.ts

@@ -3,16 +3,16 @@ import * as c from 'chalk';
 import * as openApiValidator from 'swagger2openapi/validate';
 
 import * as uuid from 'uuid';
-import { ILog, IParameterConfig, IServerlessFunctionConfig, IServiceDescription } from './types';
+import { IDefinitionConfig, ILog, IParameterConfig, IServerlessFunctionConfig } from './types';
 import { clone, merge } from './utils';
 
-export class DocumentGenerator {
+export class DefinitionGenerator {
   // The OpenAPI version we currently validate against
-  private openapiVersion = '3.0.0-RC1';
+  public version = '3.0.0-RC1';
 
   // Base configuration object
-  private config = {
-    openapi: this.openapiVersion,
+  public definition = {
+    openapi: this.version,
     description: '',
     version: '0.0.0',
     title: '',
@@ -22,65 +22,64 @@ export class DocumentGenerator {
     },
   };
 
-  private serviceDescriptor: IServiceDescription;
+  private config: IDefinitionConfig;
   private log: ILog;
 
   /**
    * Constructor
    * @param serviceDescriptor IServiceDescription
    */
-  constructor ({ log, serviceDescriptor }: {
+  constructor ({ log, config }: {
     log: ILog,
-    serviceDescriptor: IServiceDescription,
+    config: IDefinitionConfig,
   }) {
-    this.serviceDescriptor = clone(serviceDescriptor);
+    this.config = clone(config);
     this.log = log;
+  }
+
+  public parse () {
+    const {
+      title = '',
+      description = '',
+      version = uuid.v4(),
+      models,
+    } = this.config;
 
-    merge(this.config, {
-      openapi: this.openapiVersion,
+    merge(this.definition, {
+      openapi: this.version,
       servers: [],
-      info: {
-        title: serviceDescriptor.summary || '',
-        description: serviceDescriptor.description || '',
-        version: serviceDescriptor.version || uuid.v4(),
-      },
+      info: { title, description, version },
       paths: {},
       components: {
         schemas: {},
         securitySchemes: {},
       },
     });
 
-    for (const model of serviceDescriptor.models) {
-      this.config.components.schemas[model.name] = this.cleanSchema(dereference(model.schema));
+    if (models) {
+      for (const model of models) {
+        this.definition.components.schemas[model.name] = this.cleanSchema(
+          dereference(model.schema),
+        );
+      }
     }
-  }
-
-  public generate () {
-    const result: any = {};
-    this.log(`${ c.bold.yellow('[VALIDATION]') } Validating OpenAPI generated output\n`);
 
-    try {
-      openApiValidator.validateSync(this.config, result);
+    return this;
+  }
 
-      this.log(`${ c.bold.green('[VALIDATION]') } OpenAPI valid: ${c.bold.green('true')}\n\n`);
+  public validate (): { valid: boolean, context: string[], warnings: any[] } {
+    const payload: any = {};
 
-      return this.config;
-    } catch (e) {
-      this.log(
-        `${c.bold.red('[VALIDATION]')} Failed to validate OpenAPI document: \n\n${c.yellow(e.message)}\n\n` +
-        `${c.bold.green('Path:')} ${JSON.stringify(result, null, 2)}\n`,
-      );
+    openApiValidator.validateSync(this.definition, payload);
 
-      throw new Error('Failed to validate OpenAPI document');
-    }
+    return payload;
   }
 
   /**
    * Add Paths to OpenAPI Configuration from Serverless function documentation
    * @param config Add
    */
-  public addPathsFromFunctionConfig (config: IServerlessFunctionConfig[]): void {
+  public readFunctions (config: IServerlessFunctionConfig[]): void {
     // loop through function configurations
     for (const funcConfig of config) {
       // loop through http events
@@ -102,7 +101,7 @@ export class DocumentGenerator {
             },
           };
           // merge path configuration into main configuration
-          merge(this.config.paths, pathConfig);
+          merge(this.definition.paths, pathConfig);
         }
       }
     }
@@ -179,7 +178,6 @@ export class DocumentGenerator {
             : parameter.style === 'form';
         }
 
-        // console.log(parameter);
         if (parameter.schema) {
           parameterConfig.schema = this.cleanSchema(parameter.schema);
         }
@@ -190,7 +188,6 @@ export class DocumentGenerator {
           parameterConfig.examples = parameter.examples;
         }
 
-        // Add parameter config to parameters array
         parameters.push(parameterConfig);
       }
     }
@@ -210,7 +207,7 @@ export class DocumentGenerator {
       // For each request model type (Sorted by "Content-Type")
       for (const requestModelType of Object.keys(documentationConfig.requestModels)) {
         // get schema reference information
-        const requestModel = this.serviceDescriptor.models.filter(
+        const requestModel = this.config.models.filter(
           (model) => model.name === documentationConfig.requestModels[requestModelType],
         ).pop();
 
@@ -287,7 +284,7 @@ export class DocumentGenerator {
   private getResponseContent (response) {
     const content = {};
     for (const responseKey of Object.keys(response)) {
-      const responseModel = this.serviceDescriptor.models.filter(
+      const responseModel = this.config.models.filter(
           (model) => model.name === response[responseKey],
         ).pop();
       if (responseModel) {

src/ServerlessOpenApiDocumentation.ts

@@ -1,8 +1,8 @@
 import * as c from 'chalk';
 import * as fs from 'fs';
 import * as YAML from 'js-yaml';
-import { DocumentGenerator } from './DocumentGenerator';
-import { IConfigType, ILog } from './types';
+import { DefinitionGenerator } from './DefinitionGenerator';
+import { IDefinitionType, ILog } from './types';
 import { merge } from './utils';
 
 export class ServerlessOpenApiDocumentation {
@@ -70,8 +70,8 @@ export class ServerlessOpenApiDocumentation {
    * Processes CLI input by reading the input from serverless
    * @returns config IConfigType
    */
-  private processCliInput (): IConfigType {
-    const config: IConfigType = {
+  private processCliInput (): IDefinitionType {
+    const config: IDefinitionType = {
       format: 'yaml',
       file: 'openapi.yml',
       indent: 2,
@@ -103,40 +103,55 @@ export class ServerlessOpenApiDocumentation {
   private generate () {
     this.log(c.bold.underline('OpenAPI v3 Documentation Generator\n\n'));
     // Instantiate DocumentGenerator
-    const generator = new DocumentGenerator({
-      serviceDescriptor: this.customVars.documentation,
+    const generator = new DefinitionGenerator({
+      config: this.customVars.documentation,
       log: this.log,
     });
 
+    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);
     });
 
     // Add Paths to OpenAPI Output from Function Configuration
-    generator.addPathsFromFunctionConfig(funcConfigs);
+    generator.readFunctions(funcConfigs);
 
     // Process CLI Input options
     const config = this.processCliInput();
 
-    // Generate the resulting OpenAPI Object
-    const outputObject = generator.generate();
+    this.log(`${ c.bold.yellow('[VALIDATION]') } Validating OpenAPI generated output\n`);
+
+    const validation = generator.validate();
+
+    if (validation.valid) {
+      this.log(`${ c.bold.green('[VALIDATION]') } OpenAPI valid: ${c.bold.green('true')}\n\n`);
+    } else {
+      this.log(
+        `${c.bold.red('[VALIDATION]')} Failed to validate OpenAPI document: \n\n` +
+        `${c.bold.green('Path:')} ${JSON.stringify(validation, null, 2)}\n`,
+      );
+    }
+
+    const { definition } = generator;
 
     // Output the OpenAPI document to the correct format
-    let outputContent = '';
+
+    let output;
     switch (config.format.toLowerCase()) {
     case 'json':
-      outputContent = JSON.stringify(outputObject, null, config.indent);
+      output = JSON.stringify(definition, null, config.indent);
       break;
     case 'yaml':
     default:
-      outputContent = YAML.safeDump(outputObject, { indent: config.indent });
+      output = YAML.safeDump(definition, { indent: config.indent });
       break;
     }
 
-    // Write to disk
-    fs.writeFileSync(config.file, outputContent);
+    fs.writeFileSync(config.file, output);
+
     this.log(`${ c.bold.green('[SUCCESS]') } Output file to "${c.bold.red(config.file)}"\n`);
   }
 }

src/__tests__/DocumentGenerator.spec.ts src/__tests__/DefinitionGenerator.spec.tssrc/__tests__/DocumentGenerator.spec.ts renamed to src/__tests__/DefinitionGenerator.spec.ts

@@ -1,6 +1,6 @@
 import * as path from 'path';
 import * as Serverless from 'serverless';
-import { DocumentGenerator } from '../DocumentGenerator';
+import { DefinitionGenerator } from '../DefinitionGenerator';
 
 class ServerlessInterface extends Serverless {
   public service: any = {};
@@ -27,7 +27,7 @@ describe('OpenAPI Documentation Generator', () => {
     await sls.variables.populateService();
 
     if ('documentation' in sls.service.custom) {
-      const docGen = new DocumentGenerator(sls.service.custom.documentation);
+      const docGen = new DefinitionGenerator(sls.service.custom.documentation);
 
       expect(docGen).not.toBeNull();
     } else {

src/types.ts

@@ -8,15 +8,15 @@ export interface IModels {
   example: object;
 }
 
-export interface IServiceDescription {
-  version?: string;
-  summary: string;
+export interface IDefinitionConfig {
+  title: string;
   description: string;
+  version?: string;
   models: IModels[];
 }
 
-export interface IConfigType {
-  file: string; // Foo blah
+export interface IDefinitionType {
+  file: string;
   format: 'yaml' | 'json';
   indent: number;
 }