Various improvements, see CHANGELOG

Author: Brendan Abbott

CHANGELOG.md

@@ -0,0 +1,23 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](http://keepachangelog.com/en/1.0.0/)
+and this project adheres to [Semantic Versioning](http://semver.org/spec/v2.0.0.html).
+
+## [Unreleased]
+
+## Changed
+
+- Plugin now generates OpenAPI documentation with a version of `3.0.0` instead of `3.0.0-RC2`.
+- Operation now supports `deprecated` and `tags` properties.
+- Parameters now support the `content` property.
+- Updated various build dependencies.
+
+## Fixed
+
+- Handle when `models` is not iterable.
+
+## [v0.2.1] - 2017-07-07
+
+Last release prior to CHANGELOG being added.

README.md

@@ -4,9 +4,9 @@
 [![Travis CI](https://img.shields.io/travis/temando/serverless-openapi-documentation.svg)](https://travis-ci.org/temando/serverless-openapi-documentation)
 [![JavaScript Style Guide](https://img.shields.io/badge/code_style-standard-brightgreen.svg)](https://standardjs.com)
 
-Generates [**OpenAPI 3.0 RC2**](https://github.com/OAI/OpenAPI-Specification/tree/OpenAPI.next) documentation from serverless configuration files. OpenAPI is formerly known as Swagger. The configuration is inspired by the format used in [serverless-aws-documentation](https://www.npmjs.com/package/serverless-aws-documentation).
+Generates [**OpenAPI 3.0.0**](https://github.com/OAI/OpenAPI-Specification/blob/3.0.0/versions/3.0.0.md) documentation from serverless configuration files. OpenAPI is formerly known as Swagger. The configuration is inspired by the format used in [serverless-aws-documentation](https://www.npmjs.com/package/serverless-aws-documentation).
 
-Works well with [Lincoln Open Api Renderer](https://github.com/temando/open-api-renderer).
+Works well with [Lincoln OpenAPI Renderer](https://github.com/temando/open-api-renderer).
 
 ---
 
@@ -42,7 +42,7 @@ Plugin: ServerlessOpenAPIDocumentation
 openapi generate  ...................... Generate OpenAPI v3 Documentation
     --output / -o ...................... Output file location [default: openapi.yml|json]
     --format / -f ...................... OpenAPI file format (yml|json) [default: yml]
-    --indent / -i ...................... File indentation in spaces[default: 2]
+    --indent / -i ...................... File indentation in spaces [default: 2]
     --help / -h   ...................... Help
 ```
 
@@ -58,7 +58,7 @@ The `custom` section of your `serverless.yml` can be configured as below:
 custom:
   documentation:
     version: '1'
-    summary: 'My API'
+    title: 'My API'
     description: 'This is my API'
     models: {}
 ```
@@ -73,9 +73,9 @@ functions:
   myFunc:
     events:
       - http:
-          path: getStuff
-          method: get
-          documentation: ${file(serverless.doc.yml):endpoints.myFunc}
+        path: getStuff
+        method: get
+        documentation: ${file(serverless.doc.yml):endpoints.myFunc}
 ```
 
 For more info on `serverless.yml` syntax, see their docs.
@@ -333,6 +333,8 @@ serverless | grep "ServerlessOpenAPIDocumentation"
 
 It should return `ServerlessOpenAPIDocumentation` as one of the plugins on the list.
 
+> Note: Add this plugin _after_ `serverless-offline` to prevent issues with `String.replaceAll` being overridden incorrectly.
+
 ## License
 
 MIT

package.json

@@ -33,8 +33,9 @@
     "build": "scripts/build.bash"
   },
   "devDependencies": {
+    "@types/bluebird": "^3.5.8",
     "@types/chalk": "^0.4.31",
-    "@types/fs-extra": "^3.0.3",
+    "@types/fs-extra": "^4.0.0",
     "@types/jest": "^20.0.2",
     "@types/js-yaml": "^3.5.31",
     "@types/node": "^8.0.7",
@@ -48,11 +49,10 @@
     "typescript": "^2.4.1"
   },
   "dependencies": {
-    "@jdw/jst": "^1.0.0",
-    "@types/bluebird": "^3.5.8",
+    "@jdw/jst": "^2.0.0-beta.9",
     "bluebird": "^3.5.0",
     "chalk": "^2.0.1",
-    "fs-extra": "^3.0.1",
+    "fs-extra": "^4.0.1",
     "js-yaml": "^3.8.4",
     "lutils": "^2.4.0",
     "swagger2openapi": "^2.5.0",

src/DefinitionGenerator.ts

@@ -1,13 +1,13 @@
 import { dereference } from '@jdw/jst';
-import * as openApiValidator from 'swagger2openapi/validate';
-
+// tslint:disable-next-line no-submodule-imports
+import { validateSync as openApiValidatorSync } from 'swagger2openapi/validate';
 import * as uuid from 'uuid';
-import { IDefinition, IDefinitionConfig, IParameterConfig, IServerlessFunctionConfig } from './types';
-import { clone, merge } from './utils';
+import { IDefinition, IDefinitionConfig, IOperation, IParameterConfig, IServerlessFunctionConfig } from './types';
+import { clone, isIterable, merge } from './utils';
 
 export class DefinitionGenerator {
   // The OpenAPI version we currently validate against
-  public version = '3.0.0-RC2';
+  public version = '3.0.0';
 
   // Base configuration object
   public definition = <IDefinition> {
@@ -43,7 +43,7 @@ export class DefinitionGenerator {
       },
     });
 
-    if (models) {
+    if (isIterable(models)) {
       for (const model of models) {
         this.definition.components.schemas[model.name] = this.cleanSchema(
           dereference(model.schema),
@@ -58,9 +58,9 @@ export class DefinitionGenerator {
     const payload: any = {};
 
     try {
-      openApiValidator.validateSync(this.definition, payload);
+      openApiValidatorSync(this.definition, payload);
     } catch (error) {
-      payload.error = JSON.parse(error.message.replace(/^Failed OpenAPI3 schema validation: /, ''));
+      payload.error = error.message;
     }
 
     return payload;
@@ -78,18 +78,13 @@ export class DefinitionGenerator {
         const httpEventConfig = httpEvent.http;
 
         if (httpEventConfig.documentation) {
-          const documentationConfig = httpEventConfig.documentation;
           // Build OpenAPI path configuration structure for each method
           const pathConfig = {
             [`/${httpEventConfig.path}`]: {
-              [httpEventConfig.method]: {
-                operationId: funcConfig._functionName,
-                summary: documentationConfig.summary || '',
-                description: documentationConfig.description || '',
-                responses: this.getResponsesFromConfig(documentationConfig),
-                parameters: this.getParametersFromConfig(documentationConfig),
-                requestBody: this.getRequestBodiesFromConfig(documentationConfig),
-              },
+              [httpEventConfig.method]: this.getOperationFromConfig(
+                funcConfig._functionName,
+                httpEventConfig.documentation,
+              ),
             },
           };
 
@@ -117,6 +112,26 @@ export class DefinitionGenerator {
     return cleanedSchema;
   }
 
+  /**
+   * Generate Operation objects from the Serverless Config.
+   *
+   * @link https://github.com/OAI/OpenAPI-Specification/blob/3.0.0/versions/3.0.0.md#operationObject
+   * @param funcName
+   * @param documentationConfig
+   */
+  private getOperationFromConfig (funcName: string, documentationConfig): IOperation {
+    return {
+      operationId: funcName,
+      tags: documentationConfig.tags || [],
+      deprecated: documentationConfig.deprecated || false,
+      summary: documentationConfig.summary || '',
+      description: documentationConfig.description || '',
+      parameters: this.getParametersFromConfig(documentationConfig),
+      requestBody: this.getRequestBodiesFromConfig(documentationConfig),
+      responses: this.getResponsesFromConfig(documentationConfig),
+    };
+  }
+
   /**
    * Derives Path, Query and Request header parameters from Serverless documentation
    * @param documentationConfig
@@ -181,6 +196,10 @@ export class DefinitionGenerator {
           parameterConfig.examples = parameter.examples;
         }
 
+        if (parameter.content) {
+          parameterConfig.content = parameter.content;
+        }
+
         parameters.push(parameterConfig);
       }
     }

src/ServerlessOpenApiDocumentation.ts

@@ -48,7 +48,7 @@ export class ServerlessOpenApiDocumentation {
                 shortcut: 'f',
               },
               indent: {
-                usage: 'File indentation in spaces[default: 2]',
+                usage: 'File indentation in spaces [default: 2]',
                 shortcut: 'i',
               },
             },
@@ -128,14 +128,18 @@ export class ServerlessOpenApiDocumentation {
       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`);
-      this.log(`${c.bold.green('Path:')} ${JSON.stringify(validation.context, null, 2)}\n`);
-
-      for (const info of validation.error) {
-        this.log(c.grey('\n\n--------\n\n'));
-        this.log(' ', c.blue(info.dataPath), '\n');
-        this.log(' ', info.schemaPath, c.bold.yellow(info.message));
-        this.log(c.grey('\n\n--------\n\n'));
-        this.log(`${inspect(info, { colors: true, depth: 2 })}\n\n`);
+      this.log(`${c.bold.green('Context:')} ${JSON.stringify(validation.context, null, 2)}\n`);
+
+      if (typeof validation.error === 'string') {
+        this.log(`${validation.error}\n\n`);
+      } else {
+        for (const info of validation.error) {
+          this.log(c.grey('\n\n--------\n\n'));
+          this.log(' ', c.blue(info.dataPath), '\n');
+          this.log(' ', info.schemaPath, c.bold.yellow(info.message));
+          this.log(c.grey('\n\n--------\n\n'));
+          this.log(`${inspect(info, { colors: true, depth: 2 })}\n\n`);
+        }
       }
     }
 

src/index.ts

@@ -1,4 +1,5 @@
 import { ServerlessOpenApiDocumentation } from './ServerlessOpenApiDocumentation';
 
+// tslint:disable-next-line no-default-export
 export default ServerlessOpenApiDocumentation;
 module.exports = ServerlessOpenApiDocumentation;

src/types.ts

@@ -29,6 +29,27 @@ export interface IServerlessFunctionConfig {
   events?: any[];
 }
 
+// TODO: We could use another TS based OpenAPI project to get type information
+// for OpenAPI definitions.
+// @see https://github.com/Mermade/awesome-openapi3#parsersmodelsvalidators
+
+// @see https://github.com/OAI/OpenAPI-Specification/blob/3.0.0/versions/3.0.0.md#operation-object
+export interface IOperation {
+  tags?: string[];
+  summary?: string;
+  description?: string;
+  externalDocs?: any;
+  operationId?: string;
+  parameters?: IParameterConfig[];
+  requestBody?: any;
+  responses?: any;
+  callbacks?: any;
+  deprecated?: boolean;
+  security?: any[];
+  servers?: any[];
+}
+
+// @see https://github.com/OAI/OpenAPI-Specification/blob/3.0.0/versions/3.0.0.md#parameterObject
 export interface IParameterConfig {
   name: string;
   in: 'path' | 'query' | 'header' | 'cookie';
@@ -41,15 +62,20 @@ export interface IParameterConfig {
   explode?: boolean;
   allowReserved?: boolean;
   example?: any;
-  examples?: [any];
+  examples?: any[];
+  content?: Map<string, any>;
 }
 
 // FIXME:
 export interface IDefinition {
   openapi: string;
-  components: any;
   info: any;
+  servers?: any[];
   paths: any;
+  components?: any;
+  security?: any[];
+  tags?: any[];
+  externalDocs: any;
 }
 
 export type ILog = (...str: string[]) => void;

src/utils.ts

@@ -2,3 +2,4 @@ import { Clone, IMerge, Merge } from 'lutils';
 
 export const merge: IMerge = new Merge({ depth: 100 }).merge;
 export const clone = new Clone({ depth: 100 }).clone;
+export const isIterable = (obj) => obj != null && typeof obj[Symbol.iterator] === 'function'

test/project/serverless.yml

@@ -11,7 +11,7 @@ functions:
   createUser:
     handler: handler.create
     events:
-      - http: 
+      - http:
           path: create
           method: post
           documentation:
@@ -38,7 +38,7 @@ functions:
             cookieParams:
               - name: SessionId
                 description: A Session ID variable
-                schema: 
+                schema:
                   type: string
             methodResponses:
               - statusCode: 201

tsconfig.json

@@ -3,17 +3,18 @@
     "target": "es6",
     "module": "commonjs",
     "moduleResolution": "node",
-    "outDir":"./build",
+    "outDir": "./build",
     "sourceMap": true,
     "declaration": true,
     "noUnusedLocals": true,
     "downlevelIteration": true,
     "lib": [
       "es6",
       "es7",
-      "dom"
+      "dom",
+      "esnext.asynciterable"
     ]
   },
-  "exclude": [],
-  "include": [ "src/**/*" ]
+  "include": [ "src/**/*" ],
+  "exclude": [ "node_modules" ]
 }