Refactor build to dist, add more test scripts and fix brittle test paths

Author: nfour

.gitignore

@@ -1,6 +1,6 @@
 node_modules
 /npm-*
-/dist
+/build
 .coverage
 .directory
 .DS_STORE*

.travis.yml

@@ -10,6 +10,7 @@ install:
 script:
   - yarn lint
   - yarn build
+  - yarn test:build
   - DEBUG=true yarn test:coverage
 
 deploy:

jest.config.js

@@ -6,6 +6,7 @@ module.exports = {
   "coverageDirectory": ".coverage",
   "testPathIgnorePatterns": [
     "/node_modules/",
+    "/build/",
     "d.ts"
   ]
 }

package.json

@@ -2,21 +2,19 @@
   "name": "serverless-openapi-documentation",
   "version": "0.0.0",
   "description": "Serverless 1.0 plugin to generate OpenAPI V3 documentation from serverless configuration",
-  "main": "dist/index.js",
+  "main": "index.js",
   "author": "Abilio Henrique <abilio.henrique@temando.com>",
   "contributors": [
     "Abilio Henrique <abilio.henrique@temando.com>",
     "nfour <novus.nfour@gmail.com>"
   ],
   "license": "MIT",
-  "files": [
-    "dist"
-  ],
   "scripts": {
     "test": "jest",
+    "test:build": "jest -c '{}' build",
     "test:coverage": "jest --coverage",
     "lint": "tslint 'src/**/*.ts'",
-    "release": "cd dist && npm publish",
+    "release": "cd build && npm publish",
     "build": "scripts/build.bash"
   },
   "devDependencies": {

scripts/build.bash

@@ -1,14 +1,14 @@
 #!/bin/bash
 
 # Clean
-rm -rf dist
-mkdir dist
+rm -rf build
+mkdir build
 
 # Copy latent, belonging to the index module
-rsync -am . ./dist  --exclude '*/*' --include '*' 
+rsync -am . ./build  --exclude '*/*' --include '*' 
 
 # Copy latent files from source, recursively
-rsync -am  ./src/* ./dist --exclude '*.ts'
+rsync -am  ./src/* ./build --exclude '*.ts'
 
 # Build typescript
 yarn tsc

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

@@ -6,7 +6,7 @@ import * as uuid from 'uuid';
 import { IParameterConfig, IServerlessFunctionConfig, IServiceDescription } from './types';
 import { clone, merge } from './utils';
 
-export default class DocumentGenerator {
+export class DocumentGenerator {
   // The OpenAPI version we currently validate against
   private openapiVersion = '3.0.0-RC1';
 

src/ServerlessOpenApiDocumentation.ts

@@ -0,0 +1,134 @@
+import * as c from 'chalk';
+import * as fs from 'fs';
+import * as YAML from 'js-yaml';
+import { DocumentGenerator } from './DocumentGenerator';
+import { IConfigType } from './types';
+import { merge } from './utils';
+
+export class ServerlessOpenApiDocumentation {
+  public hooks;
+  public commands;
+  /** Serverless Instance */
+  private serverless;
+  /** CLI options */
+  private options;
+  /** Serverless Service Custom vars */
+  private customVars;
+
+  /**
+   * Constructor
+   * @param serverless
+   * @param options
+   */
+  constructor (serverless, options) {
+    // pull the serverless instance into our class vars
+    this.serverless = serverless;
+    // pull the CLI options into our class vars
+    this.options = options;
+    // Serverless service custom variables
+    this.customVars = this.serverless.variables.service.custom;
+
+    // Declare the commands this plugin exposes for the Serverless CLI
+    this.commands = {
+      openapi: {
+        commands: {
+          generate: {
+            lifecycleEvents: [
+              'serverless',
+            ],
+            usage: 'Generate OpenAPI v3 Documentation',
+            options: {
+              output: {
+                usage: 'Output file location [default: openapi.yml|json]',
+                shortcut: 'o',
+              },
+              format: {
+                usage: 'OpenAPI file format (yml|json) [default: yml]',
+                shortcut: 'f',
+              },
+              indent: {
+                usage: 'File indentation in spaces[default: 2]',
+                shortcut: 'i',
+              },
+            },
+          },
+        },
+      },
+    };
+
+    // Declare the hooks our plugin is interested in
+    this.hooks = {
+      'openapi:generate:serverless': this.generate.bind(this),
+    };
+  }
+
+  /**
+   * Processes CLI input by reading the input from serverless
+   * @returns config IConfigType
+   */
+  private processCliInput (): IConfigType {
+    const config: IConfigType = {
+      format: 'yaml',
+      file: 'openapi.yml',
+      indent: 2,
+    };
+
+    config.indent = this.serverless.processedInput.options.indent || 2;
+    config.format = this.serverless.processedInput.options.format || 'yaml';
+
+    if (['yaml', 'json'].indexOf(config.format.toLowerCase()) < 0) {
+      throw new Error('Invalid Output Format Specified - must be one of "yaml" or "json"');
+    }
+
+    config.file = this.serverless.processedInput.options.output ||
+      ((config.format === 'yaml') ? 'openapi.yml' : 'openapi.json');
+
+    process.stdout.write(
+      `${c.bold.green('[OPTIONS]')} ` +
+      `format: "${c.bold.red(config.format)}", ` +
+      `output file: "${c.bold.red(config.file)}", ` +
+      `indentation: "${c.bold.red(String(config.indent))}"\n\n`,
+      );
+    return config;
+  }
+
+  /**
+   * Generates OpenAPI Documentation based on serverless configuration and functions
+   */
+  private generate () {
+    process.stdout.write(c.bold.underline('OpenAPI v3 Documentation Generator\n\n'));
+    // Instantiate DocumentGenerator
+    const dg = new DocumentGenerator(this.customVars.documentation);
+
+    // 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
+    dg.addPathsFromFunctionConfig(funcConfigs);
+
+    // Process CLI Input options
+    const config = this.processCliInput();
+
+    // Generate the resulting OpenAPI Object
+    const outputObject = dg.generate();
+
+    // Output the OpenAPI document to the correct format
+    let outputContent = '';
+    switch (config.format.toLowerCase()) {
+    case 'json':
+      outputContent = JSON.stringify(outputObject, null, config.indent);
+      break;
+    case 'yaml':
+    default:
+      outputContent = YAML.safeDump(outputObject, { indent: config.indent });
+      break;
+    }
+
+    // Write to disk
+    fs.writeFileSync(config.file, outputContent);
+    process.stdout.write(`${ c.bold.green('[SUCCESS]') } Output file to "${c.bold.red(config.file)}"\n`);
+  }
+}

test/openapi-generate.test.ts src/__tests__/DocumentGenerator.spec.tstest/openapi-generate.test.ts renamed to src/__tests__/DocumentGenerator.spec.ts

@@ -1,7 +1,6 @@
-import * as fs from 'fs-extra';
 import * as path from 'path';
 import * as Serverless from 'serverless';
-import DocumentGenerator from '../src/generate';
+import { DocumentGenerator } from '../DocumentGenerator';
 
 class ServerlessInterface extends Serverless {
   public service: any = {};
@@ -13,21 +12,24 @@ class ServerlessInterface extends Serverless {
 
 describe('OpenAPI Documentation Generator', () => {
   it('Generates OpenAPI document', async () => {
-    const serverlessConfig = await fs.readFile('test/fixtures/serverless.yml');
+    const servicePath = path.join(__dirname, './fixtures');
+    const serverlessYamlPath = path.join(servicePath, './serverless.yml');
     const sls: ServerlessInterface = new Serverless();
 
     sls.config.update({
-      servicePath: path.join(process.cwd(), 'test/fixtures'),
+      servicePath,
     });
 
-    const config = await sls.yamlParser.parse(path.join(process.cwd(), 'test/fixtures/serverless.yml'));
+    const config = await sls.yamlParser.parse(serverlessYamlPath);
     sls.pluginManager.cliOptions = { stage: 'dev' };
 
     await sls.service.load(config);
     await sls.variables.populateService();
 
     if ('documentation' in sls.service.custom) {
       const docGen = new DocumentGenerator(sls.service.custom.documentation);
+
+      expect(docGen).not.toBeNull();
     } else {
       throw new Error('Cannot find "documentation" in custom section of "serverless.yml"');
     }