serverless-openapi-documenter 0.0.12 → 0.0.16

package/.github/workflows/node.yml

@@ -0,0 +1,31 @@
+# This workflow will do a clean installation of node dependencies, cache/restore them, build the source code and run tests across different versions of node
+# For more information see: https://help.github.com/actions/language-and-framework-guides/using-nodejs-with-github-actions
+
+name: Node.js CI
+
+on:
+  push:
+    branches: [ "main" ]
+  pull_request:
+    branches: [ "main" ]
+
+jobs:
+  build:
+
+    runs-on: ubuntu-latest
+
+    strategy:
+      matrix:
+        node-version: [14.x, 16.x]
+        # See supported Node.js release schedule at https://nodejs.org/en/about/releases/
+
+    steps:
+    - uses: actions/checkout@v3
+    - name: Use Node.js ${{ matrix.node-version }}
+      uses: actions/setup-node@v3
+      with:
+        node-version: ${{ matrix.node-version }}
+        cache: 'npm'
+    - run: npm ci
+    - run: npm run build --if-present
+    - run: npm test

package/README.md

@@ -9,19 +9,21 @@
   </a>
 </p>
 
+![node.js tests](https://github.com/JaredCE/serverless-openapi-documenter/actions/workflows/node.js.yml/badge.svg)
+
 This will generate an OpenAPI V3 (up to v3.0.3) file for you from your serverless file.  It can optionally generate a Postman Collection V2 from the OpenAPI file for you too.
 
 Originally based off of: https://github.com/temando/serverless-openapi-documentation
 
 ## Install
 
-This plugin works for Serverless 2.x and up.
+This plugin works for Serverless 2.x and up and only supports node.js 14 and up.
 
 To add this plugin to your package.json:
 
 **Using npm:**
 ```bash
-npm install --save-dev serverless-openapi-documenter 
+npm install --save-dev serverless-openapi-documenter
 ```
 
 Next you need to add the plugin to the `plugins` section of your `serverless.yml` file.
@@ -112,7 +114,6 @@ custom:
     version: '1'
     title: 'My API'
     description: 'This is my API'
-    models: {}
     externalDocumentation:
       url: https://google.com
       description: A link to google
@@ -125,8 +126,11 @@ custom:
         externalDocumentation:
           url: https://npmjs.com
           description: A link to npm
+    models: {}
 ```
 
+Mostly everything here is optional.  A version from a UUID will be generated for you if you don't specify one, title will be the name of your service if you don't specify one.
+
 These configurations can be quite verbose; you can separate it out into it's own file, such as `serverless.doc.yml` as below:
 
 ```yml
@@ -146,9 +150,10 @@ For more info on `serverless.yml` syntax, see their docs.
 
 #### Models
 
-Models contain additional information that you can use to define schemas for endpoints.  You must define the *content type* for each schema that you provide in the models.
+There are two ways to write the Models.  Models contain additional information that you can use to define schemas for endpoints.  You must define the *content type* for each schema that you provide in the models.
 
-The *required* directives for the models section are as follow:
+The first way of writing the model is:
+*required* directives for the models section are as follow:
 
 * `name`: the name of the schema
 * `description`: a description of the schema
@@ -180,6 +185,40 @@ custom:
                   type: "string"
 ```
 
+The Second way of writing the models:
+
+* `name`: the name of the schema
+* `description`: a description of the schema
+* `content`: an Object made up of the contentType and the schema, as shown below
+
+```yml
+custom:
+  documentation:
+    models:
+      - name: "ErrorResponse"
+        description: "This is an error"
+        content:
+          application/json:
+            schema: ${file(models/ErrorResponse.json)}
+      - name: "PutDocumentResponse"
+        description: "PUT Document response model (external reference example)"
+        content:
+          application/json:
+            schema: ${file(models/PutDocumentResponse.json)}
+      - name: "PutDocumentRequest"
+        description: "PUT Document request model (inline example)"
+        content:
+          application/json:
+            schema:
+              $schema: "http://json-schema.org/draft-04/schema#"
+              properties:
+                SomeObject:
+                  type: "object"
+                  properties:
+                    SomeAttribute:
+                      type: "string"
+```
+
 #### Functions
 
 To define the documentation for a given function event, you need to create a `documentation` attribute for your http event in your `serverless.yml` file.
@@ -206,11 +245,12 @@ The `documentation` section of the event configuration can contain the following
 ```yml
 functions:
   createUser:
-    handler: "handler.create"
+    handler: handler.create
     events:
       - http:
-        path: "create"
-        method: "post"
+        path: create
+        method: post
+        summary:
         documentation:
           summary: "Create User"
           description: "Creates a user and then sends a generated password email"
@@ -375,7 +415,7 @@ Please view the example [serverless.yml](test/serverless\ 2/serverless.yml).
 
 ## Notes on schemas
 
-Schemas can be either: inline, in file or externally hosted.  If they're inline or in file, the plugin will attempt to normalise the schema to [OpenAPI 3.0.X specification](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.0.0.md#schemaObject).  
+Schemas can be either: inline, in file or externally hosted.  If they're inline or in file, the plugin will attempt to normalise the schema to [OpenAPI 3.0.X specification](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.0.0.md#schemaObject).
 
 If they exist as an external reference, for instance:
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "serverless-openapi-documenter",
-  "version": "0.0.12",
+  "version": "0.0.16",
   "description": "Generate OpenAPI v3 documentation and Postman Collections from your Serverless Config",
   "main": "index.js",
   "keywords": [
@@ -14,7 +14,7 @@
     "Postman-Collections"
   ],
   "scripts": {
-    "test": "echo \"Error: no test specified\" && exit 1"
+    "test": "mocha --config './test/.mocharc.js'"
   },
   "author": {
     "name": "Jared Evans"
@@ -39,5 +39,10 @@
   },
   "engines": {
     "node": ">=14"
+  },
+  "devDependencies": {
+    "chai": "^4.3.6",
+    "mocha": "^10.0.0",
+    "sinon": "^14.0.0"
   }
 }

package/src/definitionGenerator.js

@@ -9,7 +9,7 @@ const $RefParser = require("@apidevtools/json-schema-ref-parser");
 
 class DefinitionGenerator {
     constructor(serverless, options = {}) {
-        this.version = serverless.processedInput.options.openApiVersion || '3.0.0'
+        this.version = serverless?.processedInput?.options?.openApiVersion || '3.0.0'
 
         this.serverless = serverless
         this.httpKeys = {
@@ -27,13 +27,14 @@ class DefinitionGenerator {
         }
 
         this.operationIds = []
+        this.schemaIDs = []
 
         try {
             this.refParserOptions = require(path.resolve('options', 'ref-parser.js'))
         } catch (err) {
             this.refParserOptions = {}
         }
-        
+
     }
 
     async parse() {
@@ -42,7 +43,7 @@ class DefinitionGenerator {
             .catch(err => {
                 throw err
             })
-        
+
         if (this.serverless.service.custom.documentation.servers) {
             const servers = this.createServers(this.serverless.service.custom.documentation.servers)
             Object.assign(this.openAPI, {servers: servers})
@@ -73,11 +74,10 @@ class DefinitionGenerator {
     async createPaths() {
         const paths = {}
         const httpFunctions = this.getHTTPFunctions()
-
         for (const httpFunction of httpFunctions) {
             for (const event of httpFunction.event) {
                 if (event?.http?.documentation || event?.httpApi?.documentation) {
-                    const documentation = event.http.documentation || event.httpApi.documentation
+                    const documentation = event?.http?.documentation || event?.httpApi?.documentation
 
                     let opId
                     if (this.operationIds.includes(httpFunction.functionInfo.name) === false) {
@@ -87,11 +87,11 @@ class DefinitionGenerator {
                         opId = `${httpFunction.functionInfo.name}-${uuid()}`
                     }
 
-                    const path = await this.createOperationObject(event.http.method || event.httpApi.method, documentation, opId)
+                    const path = await this.createOperationObject(event?.http?.method || event?.httpApi?.method, documentation, opId)
                         .catch(err => {
                             throw err
                         })
-                    
+
                     if (httpFunction.functionInfo?.summary)
                         path.summary = httpFunction.functionInfo.summary
 
@@ -103,10 +103,10 @@ class DefinitionGenerator {
                         path.servers = servers
                     }
 
-                    let slashPath = event.http.path
+                    let slashPath = event?.http?.path || event.httpApi?.path
                     const pathStart = new RegExp(/^\//, 'g')
                     if (pathStart.test(slashPath) === false) {
-                        slashPath = `/${event.http.path}`
+                        slashPath = `/${event?.http?.path||event.httpApi?.path}`
                     }
 
                     Object.assign(paths, {[slashPath]: path})
@@ -152,7 +152,7 @@ class DefinitionGenerator {
         // const documentation = this.serverless.service.custom.documentation
         // if (documentation.externalDocumentation) {
         //     // Object.assign(this.openAPI, {externalDocs: {...documentation.externalDocumentation}})
-        //     return 
+        //     return
         // }
     }
 
@@ -240,7 +240,7 @@ class DefinitionGenerator {
             obj.servers = servers
         }
 
-        return {[method]: obj}
+        return {[method.toLowerCase()]: obj}
     }
 
     async createResponses(documentation) {
@@ -292,14 +292,19 @@ class DefinitionGenerator {
                 if (mediaTypeDocumentation.examples)
                     obj.examples = this.createExamples(mediaTypeDocumentation.examples)
 
-                if (mediaTypeDocumentation.content[contentKey].schema) {
-                    const schemaRef = await this.schemaCreator(mediaTypeDocumentation.content[contentKey].schema, mediaTypeDocumentation.name)
-                        .catch(err => {
-                            throw err
-                        })
-                    obj.schema = {
-                        $ref: schemaRef
-                    }
+                let schema
+                if (mediaTypeDocumentation?.content) {
+                    schema = mediaTypeDocumentation.content[contentKey].schema
+                } else if (mediaTypeDocumentation?.contentType && mediaTypeDocumentation.schema) {
+                    schema = mediaTypeDocumentation.schema
+                }
+
+                const schemaRef = await this.schemaCreator(schema, mediaTypeDocumentation.name)
+                    .catch(err => {
+                        throw err
+                    })
+                obj.schema = {
+                    $ref: schemaRef
                 }
 
                 Object.assign(mediaTypeObj, {[contentKey]: obj})
@@ -381,14 +386,33 @@ class DefinitionGenerator {
 
         if (typeof schema !== 'string' && Object.keys(schema).length > 0) {
             const convertedSchema = SchemaConvertor.convert(schema)
+
+            let schemaName = name
+            if (this.schemaIDs.includes(schemaName))
+                schemaName = `${name}-${uuid()}`
+
+            this.schemaIDs.push(schemaName)
+
             for (const key of Object.keys(convertedSchema.schemas)) {
                 if (key === 'main' || key.split('-')[0] === 'main') {
-                    const ref = `#/components/schemas/${name}`
+                    let ref = `#/components/schemas/`
+
+                    if (this.openAPI?.components?.schemas?.[name]) {
+                        if (JSON.stringify(convertedSchema.schemas[key]) === JSON.stringify(this.openAPI.components.schemas[name])) {
+                            return `${ref}${name}`
+                        }
+                    }
 
-                    addToComponents(convertedSchema.schemas[key], name)
-                    return ref
+                    addToComponents(convertedSchema.schemas[key], schemaName)
+                    return `${ref}${schemaName}`
                 } else {
-                    addToComponents(convertedSchema.schemas[key], key)
+                    if (this.openAPI?.components?.schemas?.[key]) {
+                        if (JSON.stringify(convertedSchema.schemas[key]) !== JSON.stringify(this.openAPI.components.schemas[key])) {
+                            addToComponents(convertedSchema.schemas[key], key)
+                        }
+                    } else {
+                        addToComponents(convertedSchema.schemas[key], key)
+                    }
                 }
             }
         } else {

package/src/openAPIGenerator.js

@@ -54,7 +54,6 @@ class OpenAPIGenerator {
         }
 
         this.hooks = {
-          // 'before:deploy': this.beforeDeploy.bind(this),
           'openapi:generate:serverless': this.generate.bind(this),
         };
 
@@ -76,17 +75,23 @@ class OpenAPIGenerator {
 
         this.serverless.configSchemaHandler.defineFunctionProperties('aws', {
           properties: {
-            // description: {type: 'string'},
             summary: {type: 'string'},
             servers: {anyOf: [{type:'object'}, {type:'array'}]},
           }
         })
     }
 
-    log(type = this.defaultLog, ...str) {
+    log(type = this.defaultLog, str) {
         switch(this.serverless.version[0]) {
           case '2':
-            this.serverless.cli.log(str)
+            let colouredString = str
+            if (type === 'error') {
+              colouredString = chalk.bold.red(`✖ ${str}`)
+            } else if (type === 'success') {
+              colouredString = chalk.bold.green(`✓ ${str}`)
+            }
+
+            this.serverless.cli.log(colouredString)
             break
 
           case '3':
@@ -106,32 +111,32 @@ class OpenAPIGenerator {
 
         await generator.parse()
           .catch(err => {
-            this.log('error', chalk.bold.red(`ERROR: An error was thrown generating the OpenAPI v3 documentation`))
+            this.log('error', `ERROR: An error was thrown generating the OpenAPI v3 documentation`)
             throw new this.serverless.classes.Error(err)
           })
 
         const valid = await generator.validate()
           .catch(err => {
-            this.log('error', chalk.bold.red(`ERROR: An error was thrown validating the OpenAPI v3 documentation`))
+            this.log('error', `ERROR: An error was thrown validating the OpenAPI v3 documentation`)
             throw new this.serverless.classes.Error(err)
           })
 
         if (valid)
-          this.log(this.defaultLog, chalk.bold.green('OpenAPI v3 Documentation Successfully Generated'))
+          this.log('success', 'OpenAPI v3 Documentation Successfully Generated')
 
         if (config.postmanCollection) {
           const postmanGeneration = (err, result) => {
             if (err) {
-              this.log('error', chalk.bold.red(`ERROR: An error was thrown when generating the postman collection`))
+              this.log('error', `ERROR: An error was thrown when generating the postman collection`)
               throw new this.serverless.classes.Error(err)
             }
 
-            this.log(this.defaultLog, chalk.bold.green('postman collection v2 Documentation Successfully Generated'))
+            this.log('success', 'postman collection v2 Documentation Successfully Generated')
             try {
               fs.writeFileSync(config.postmanCollection, JSON.stringify(result.output[0].data))
-              this.log(this.defaultLog, chalk.bold.green('postman collection v2 Documentation Successfully Written'))
+              this.log('success', 'postman collection v2 Documentation Successfully Written')
             } catch (err) {
-              this.log('error', chalk.bold.red(`ERROR: An error was thrown whilst writing the postman collection`))
+              this.log('error', `ERROR: An error was thrown whilst writing the postman collection`)
               throw new this.serverless.classes.Error(err)
             }
           }
@@ -155,9 +160,9 @@ class OpenAPIGenerator {
         }
         try {
           fs.writeFileSync(config.file, output);
-          this.log(this.defaultLog, chalk.bold.green('OpenAPI v3 Documentation Successfully Written'))
+          this.log('success', 'OpenAPI v3 Documentation Successfully Written')
         } catch (err) {
-          this.log('error', chalk.bold.red(`ERROR: An error was thrown whilst writing the openAPI Documentation`))
+          this.log('error', `ERROR: An error was thrown whilst writing the openAPI Documentation`)
           throw new this.serverless.classes.Error(err)
         }
     }
@@ -177,7 +182,8 @@ class OpenAPIGenerator {
       config.postmanCollection = this.serverless.processedInput.options.postmanCollection || null
 
       if (['yaml', 'json'].indexOf(config.format.toLowerCase()) < 0) {
-        throw new Error('Invalid Output Format Specified - must be one of "yaml" or "json"');
+        // throw new Error('Invalid Output Format Specified - must be one of "yaml" or "json"');
+        throw new this.serverless.classes.Error('Invalid Output Format Specified - must be one of "yaml" or "json"')
       }
 
       config.file = this.serverless.processedInput.options.output ||
@@ -185,12 +191,12 @@ class OpenAPIGenerator {
 
       this.log(
         this.defaultLog,
-        `${chalk.bold.green('[OPTIONS]')}`,
-        ` openApiVersion: "${chalk.bold.red(String(config.openApiVersion))}"`,
-        ` format: "${chalk.bold.red(config.format)}"`,
-        ` output file: "${chalk.bold.red(config.file)}"`,
-        ` indentation: "${chalk.bold.red(String(config.indent))}"`,
-        ` ${config.postmanCollection ? `postman collection: ${chalk.bold.red(config.postmanCollection)}`: `\n\n`}`
+        `${chalk.bold.green('[OPTIONS]')}
+  openApiVersion: "${chalk.bold.green(String(config.openApiVersion))}"
+  format: "${chalk.bold.green(config.format)}"
+  output file: "${chalk.bold.green(config.file)}"
+  indentation: "${chalk.bold.green(String(config.indent))}"
+  ${config.postmanCollection ? `postman collection: ${chalk.bold.green(config.postmanCollection)}`: `\n\n`}`
       )
 
       return config

package/test/.mocharc.js

@@ -0,0 +1,9 @@
+'use strict'
+
+module.exports = {
+    recursive: true,
+    reporter: 'spec',
+    spec: 'test/unit/*.spec.js',
+    watch: false,
+    'watch-files': ['src/**/*.js', 'test/**/*.spec.js'],
+}

package/test/helpers/ref-parser.js

@@ -0,0 +1,5 @@
+'use strict'
+
+module.exports = {
+    continueOnError: true,            // Don't throw on the first error
+}

package/test/helpers/serverless.js

@@ -0,0 +1,19 @@
+'use strict'
+
+module.exports = {
+    processedInput: {
+        options: {
+            openApiVersion: '3.0.1'
+        }
+    },
+    service: {
+        service: 'myAPI',
+        custom: {
+            documentation: {
+                title: 'My new API',
+                description: 'This API does things',
+                version: '0.0.1'
+            }
+        }
+    }
+}

package/test/json/complex.json

@@ -0,0 +1,91 @@
+{
+    "$comment": "JSON Schema for CSR Framework",
+    "$schema": "http://json-schema.org/draft-04/schema",
+    "definitions": {
+      "log": {
+        "type": "object",
+        "title": "Logger options",
+        "properties": {
+          "channel": {
+            "type": "string",
+            "default": "console"
+          },
+          "path": {
+            "type": "string",
+            "default": "../src/logs"
+          },
+          "template": {
+            "type": "object",
+            "properties": {
+              "message": {
+                "type": "string"
+              },
+              "file": {
+                "type": "string"
+              },
+              "dir": {
+                "type": "string"
+              }
+            }
+          },
+          "telegram": {
+            "type": "object",
+            "properties": {
+              "bot_token": {
+                "type": "string"
+              },
+              "chat_id": {
+                "type": "string"
+              }
+            },
+            "required": ["chat_id", "bot_token"]
+          }
+        }
+      },
+      "template": {
+        "type": "object",
+        "properties": {
+          "path": {
+            "type": "string"
+          },
+          "cache": {
+            "type": "string"
+          }
+        }
+      },
+      "database": {
+        "type": "object",
+        "patternProperties": {
+          ".*": {
+            "type": "object",
+            "properties": {
+              "provider": {
+                "type": "string"
+              },
+              "user": {
+                "type": "string"
+              },
+              "password": {
+                "type": "string"
+              }
+            },
+            "required": ["provider"]
+          }
+        }
+      }
+    },
+    "id": "https://json.schemastore.org/csr",
+    "properties": {
+      "log": {
+        "$ref": "#/definitions/log"
+      },
+      "template": {
+        "$ref": "#/definitions/template"
+      },
+      "database": {
+        "$ref": "#/definitions/database"
+      }
+    },
+    "title": "CSR Framework schema",
+    "type": "object"
+  }

package/test/serverless 2/serverless.yml

@@ -19,7 +19,7 @@ functions:
           documentation:
             summary: Create User
             description: Creates a user and then sends a generated password email
-            tags: 
+            tags:
               - jesus
             externalDocumentation:
               url: https://bing.com
@@ -64,12 +64,28 @@ functions:
       - http:
           path: delete
           method: delete
-
+  patchUser:
+    handler: handler.patch
+    events:
+      - httpApi:
+          path: /patch/
+          method: PATCH
+          documentation:
+            summary: Patch a User
+            description: Patch details about the user
+            tags:
+              - patching
+            methodResponses:
+              - statusCode: 200
+                responseBody:
+                  description: A user object along with generated API Keys
+                responseModels:
+                  application/json: PutDocumentResponse
 custom:
   documentation:
     description: This is a description of what this does
     version: 1.0.0
-    tags: 
+    tags:
       - name: jesus
         description: jesus was a man
         externalDocumentation:

package/test/serverless 3/serverless.yml

@@ -12,11 +12,16 @@ functions:
     handler: handler.create
     events:
       - http:
-          path: create
+          path: create/{username}
           method: post
           documentation:
             summary: Create User
             description: Creates a user and then sends a generated password email
+            tags:
+              - jesus
+            externalDocumentation:
+              url: https://bing.com
+              description: A link to bing
             requestBody:
               description: A user information object
             requestModels:
@@ -54,25 +59,30 @@ functions:
 
 custom:
   documentation:
+    description: This is a description of what this does
+    version: 1.0.0
     models:
       - name: ErrorResponse
         description: This is an error
-        contentType: application/json
-        schema: ${file(models/ErrorResponse.json)}
+        content:
+          application/json:
+            schema: ${file(../models/ErrorResponse.json)}
 
       - name: PutDocumentResponse
         description: PUT Document response model (external reference example)
-        contentType: application/json
-        schema: ${file(models/PutDocumentResponse.json)}
+        content:
+          application/json:
+            schema: ${file(../models/PutDocumentResponse.json)}
 
       - name: PutDocumentRequest
         description: PUT Document request model (inline example)
-        contentType: application/json
-        schema:
-          $schema: http://json-schema.org/draft-04/schema#
-          properties:
-            SomeObject:
-              type: object
+        content:
+          application/json:
+            schema:
+              $schema: http://json-schema.org/draft-04/schema#
               properties:
-                SomeAttribute:
-                  type: string
+                SomeObject:
+                  type: object
+                  properties:
+                    SomeAttribute:
+                      type: string

package/test/unit/definitionGenerator.spec.js

@@ -0,0 +1,603 @@
+'use strict'
+
+const fs = require('fs').promises
+const path = require('path')
+const sinon = require('sinon')
+const $RefParser = require("@apidevtools/json-schema-ref-parser");
+const expect = require('chai').expect
+
+const serverlessMock = require('../helpers/serverless')
+const DefinitionGenerator = require('../../src/definitionGenerator')
+
+describe('DefinitionGenerator', () => {
+    let mockServerless
+    const v4 = new RegExp(/^[0-9A-F]{8}-[0-9A-F]{4}-4[0-9A-F]{3}-[89AB][0-9A-F]{3}-[0-9A-F]{12}$/i);
+    beforeEach(function() {
+        mockServerless = JSON.parse(JSON.stringify(serverlessMock))
+    });
+
+    describe('constructor', () => {
+        it('should return a definitionGenerator', function() {
+            const expected = new DefinitionGenerator({}, {})
+            expect(expected).to.be.an.instanceOf(DefinitionGenerator)
+        });
+
+        it('should default to version 3.0.0 of openAPI when openAPI version is not passed in', function() {
+            let expected = new DefinitionGenerator({}, {})
+            expect(expected.version).to.be.equal('3.0.0')
+
+            let serverlessObj = {
+                processedInput: {}
+            }
+            expected = new DefinitionGenerator(serverlessObj, {})
+            expect(expected.version).to.be.equal('3.0.0')
+
+            serverlessObj.processedInput = {
+                options: {}
+            }
+            expected = new DefinitionGenerator(serverlessObj, {})
+            expect(expected.version).to.be.equal('3.0.0')
+
+            serverlessObj.processedInput.options = {
+                test: 'abc'
+            }
+
+            expected = new DefinitionGenerator(serverlessObj, {})
+            expect(expected.version).to.be.equal('3.0.0')
+
+            serverlessObj.processedInput.options = {
+                openApiVersion: null
+            }
+
+            expected = new DefinitionGenerator(serverlessObj, {})
+            expect(expected.version).to.be.equal('3.0.0')
+
+            serverlessObj.processedInput.options = {
+                openApiVersion: undefined
+            }
+
+            expected = new DefinitionGenerator(serverlessObj, {})
+            expect(expected.version).to.be.equal('3.0.0')
+
+            serverlessObj.processedInput.options = {
+                openapiVersion: undefined
+            }
+
+            expected = new DefinitionGenerator(serverlessObj, {})
+            expect(expected.version).to.be.equal('3.0.0')
+        });
+
+        it('should respect the version of openAPI when passed in', function() {
+            let serverlessObj = {
+                processedInput: {
+                    options: {
+                        openApiVersion: '3.0.0'
+                    }
+                }
+            }
+            let expected = new DefinitionGenerator(serverlessObj, {})
+            expect(expected.version).to.be.equal('3.0.0')
+
+            serverlessObj = {
+                processedInput: {
+                    options: {
+                        openApiVersion: '3.0.1'
+                    }
+                }
+            }
+            expected = new DefinitionGenerator(serverlessObj, {})
+            expect(expected.version).to.be.equal('3.0.1')
+        });
+
+        it('should correctly resolve the RefParserOptions', async function() {
+            let expected = new DefinitionGenerator({}, {})
+            expect(expected.refParserOptions).to.be.an('object')
+            expect(expected.refParserOptions).to.be.empty
+
+            await fs.mkdir(path.resolve('options'))
+                .catch(err => {
+                    console.error(err)
+                    throw err
+                })
+
+            await fs.copyFile(path.resolve('test/helpers/ref-parser.js'), path.resolve('options/ref-parser.js'))
+                .catch(err => {
+                    console.error(err)
+                    throw err
+                })
+
+            expected = new DefinitionGenerator({}, {})
+            expect(expected.refParserOptions).to.be.an('object')
+            expect(expected.refParserOptions).to.have.property('continueOnError')
+
+            await fs.rm(path.resolve('options/ref-parser.js'))
+                .catch(err => {
+                    console.error(err)
+                    throw err
+                })
+
+            await fs.rmdir(path.resolve('options'))
+                .catch(err => {
+                    console.error(err)
+                    throw err
+                })
+        });
+    });
+
+    describe('createInfo', () => {
+        it('should create openAPI info object correctly', function() {
+            const definitionGenerator = new DefinitionGenerator(mockServerless)
+            definitionGenerator.createInfo()
+
+            expect(definitionGenerator.openAPI).to.be.an('object')
+            expect(definitionGenerator.openAPI.info).to.be.an('object')
+            expect(definitionGenerator.openAPI.info).to.deep.equal(mockServerless.service.custom.documentation)
+        });
+
+        it('should use the service name when documentation title has not been supplied', function() {
+            delete mockServerless.service.custom.documentation.title
+            const definitionGenerator = new DefinitionGenerator(mockServerless)
+            definitionGenerator.createInfo()
+
+            expect(definitionGenerator.openAPI).to.be.an('object')
+            expect(definitionGenerator.openAPI.info).to.be.an('object')
+            expect(definitionGenerator.openAPI.info.title).to.be.equal(mockServerless.service.service)
+        });
+
+        it('should use the service name when documentation description has not been supplied', function() {
+            delete mockServerless.service.custom.documentation.description
+            const definitionGenerator = new DefinitionGenerator(mockServerless)
+            definitionGenerator.createInfo()
+
+            expect(definitionGenerator.openAPI).to.be.an('object')
+            expect(definitionGenerator.openAPI.info).to.be.an('object')
+            expect(definitionGenerator.openAPI.info.description).to.be.equal('')
+        });
+
+        it('should use an empty string when documentation description has not been supplied', function() {
+            delete mockServerless.service.custom.documentation.description
+            const definitionGenerator = new DefinitionGenerator(mockServerless)
+            definitionGenerator.createInfo()
+
+            expect(definitionGenerator.openAPI).to.be.an('object')
+            expect(definitionGenerator.openAPI.info).to.be.an('object')
+            expect(definitionGenerator.openAPI.info.description).to.be.equal('')
+        });
+
+        it('should generate a uuid for version when documentation version has not been supplied', function() {
+            delete mockServerless.service.custom.documentation.version
+
+            const definitionGenerator = new DefinitionGenerator(mockServerless)
+            definitionGenerator.createInfo()
+
+            expect(definitionGenerator.openAPI).to.be.an('object')
+            expect(definitionGenerator.openAPI.info).to.be.an('object')
+            expect(v4.test(definitionGenerator.openAPI.info.version)).to.be.true
+        });
+    });
+
+    describe('createTags', () => {
+        it('should add tags to the openAPI object correctly', function() {
+            mockServerless.service.custom.documentation.tags = [{name: 'tag1'}]
+
+            const definitionGenerator = new DefinitionGenerator(mockServerless)
+            definitionGenerator.createTags()
+
+            expect(definitionGenerator.openAPI).to.be.an('object')
+            expect(definitionGenerator.openAPI.tags).to.be.an('array')
+            expect(definitionGenerator.openAPI.tags[0].name).to.be.equal('tag1')
+        });
+
+        it('should not add tags when they are not defined', function() {
+            const definitionGenerator = new DefinitionGenerator(mockServerless)
+            expect(() => {
+                definitionGenerator.createTags()
+            }).to.throw()
+        });
+    });
+
+    describe('schemaCreator', () => {
+        describe('schemas that are objects', () => {
+            it('should add a simple schema to the components object', async function() {
+                const simpleSchema = {
+                    type: 'string'
+                }
+                const definitionGenerator = new DefinitionGenerator(mockServerless)
+                const expected = await definitionGenerator.schemaCreator(simpleSchema, 'simpleSchema')
+                    .catch((err) => {
+                        console.error(err)
+                    })
+
+                expect(definitionGenerator.openAPI.components.schemas).to.have.property('simpleSchema')
+                expect(JSON.stringify(definitionGenerator.openAPI.components.schemas.simpleSchema)).to.equal(JSON.stringify(simpleSchema))
+                expect(expected).to.equal('#/components/schemas/simpleSchema')
+            });
+
+            it('should add a complex schema to the components object', async function() {
+                const complexSchema = {
+                   type: 'object',
+                   properties: {
+                       error: {
+                           type: 'string'
+                       }
+                   }
+                }
+                const definitionGenerator = new DefinitionGenerator(mockServerless)
+                const expected = await definitionGenerator.schemaCreator(complexSchema, 'main')
+                    .catch((err) => {
+                        console.error(err)
+                    })
+
+                expect(definitionGenerator.openAPI.components.schemas).to.have.property('main')
+                expect(JSON.stringify(definitionGenerator.openAPI.components.schemas.main)).to.equal(JSON.stringify(complexSchema))
+                expect(expected).to.equal('#/components/schemas/main')
+            });
+
+            it('should add each definition of a complex schema to the components object', async function() {
+                const complexSchema = {
+                    "$schema": "http://json-schema.org/draft-04/schema#",
+                    "title": "JSON API Schema",
+                    "description": "This is a blah blah for responses in the JSON API format. For more, see http://jsonapi.org",
+                    "type": "object",
+                    "required": [
+                        "errors"
+                    ],
+                    "properties": {
+                        "errors": {
+                            "type": "array",
+                            "items": {
+                                "$ref": "#/definitions/error"
+                            },
+                            "uniqueItems": true
+                        }
+                    },
+                    "definitions": {
+                        "error": {
+                            "type": "object",
+                            "properties": {
+                                "id": {
+                                    "description": "A unique identifier for this particular occurrence of the problem.",
+                                    "type": "string"
+                                }
+                            }
+                        }
+                    }
+                }
+                const definitionGenerator = new DefinitionGenerator(mockServerless)
+                const expected = await definitionGenerator.schemaCreator(complexSchema, 'PutRequest')
+                    .catch((err) => {
+                        console.error(err)
+                    })
+
+                expect(definitionGenerator.openAPI.components.schemas).to.have.property('PutRequest')
+                expect(definitionGenerator.openAPI.components.schemas).to.have.property('error')
+                expect(expected).to.equal('#/components/schemas/PutRequest')
+            });
+
+            it(`should not overwrite an object that already exists in the components if they're the same`, async function() {
+                const complexSchema = {
+                    "$schema": "http://json-schema.org/draft-04/schema#",
+                    "title": "JSON API Schema",
+                    "description": "This is a blah blah for responses in the JSON API format. For more, see http://jsonapi.org",
+                    "type": "object",
+                    "required": [
+                        "errors"
+                    ],
+                    "properties": {
+                        "errors": {
+                            "type": "array",
+                            "items": {
+                                "$ref": "#/definitions/error"
+                            },
+                            "uniqueItems": true
+                        }
+                    },
+                    "definitions": {
+                        "error": {
+                            "type": "object",
+                            "properties": {
+                                "id": {
+                                    "description": "A unique identifier for this particular occurrence of the problem.",
+                                    "type": "string"
+                                }
+                            }
+                        }
+                    }
+                }
+                const definitionGenerator = new DefinitionGenerator(mockServerless)
+                let expected = await definitionGenerator.schemaCreator(complexSchema, 'PutRequest')
+                    .catch((err) => {
+                        console.error(err)
+                    })
+
+                expect(definitionGenerator.openAPI.components.schemas).to.have.property('PutRequest')
+                expect(definitionGenerator.openAPI.components.schemas).to.have.property('error')
+                expect(expected).to.equal('#/components/schemas/PutRequest')
+
+                expected = await definitionGenerator.schemaCreator(complexSchema, 'PutRequest')
+                    .catch((err) => {
+                        console.error(err)
+                    })
+
+                expect(definitionGenerator.openAPI.components.schemas).to.have.property('PutRequest')
+                expect(definitionGenerator.openAPI.components.schemas).to.have.property('error')
+                expect(expected).to.equal('#/components/schemas/PutRequest')
+            });
+
+            it(`should create a new object for a similarly named object but with different properties`, async function() {
+                const complexSchema = {
+                    "$schema": "http://json-schema.org/draft-04/schema#",
+                    "title": "JSON API Schema",
+                    "description": "This is a blah blah for responses in the JSON API format. For more, see http://jsonapi.org",
+                    "type": "object",
+                    "required": [
+                        "errors"
+                    ],
+                    "properties": {
+                        "errors": {
+                            "type": "array",
+                            "items": {
+                                "$ref": "#/definitions/error"
+                            },
+                            "uniqueItems": true
+                        }
+                    },
+                    "definitions": {
+                        "error": {
+                            "type": "object",
+                            "properties": {
+                                "id": {
+                                    "description": "A unique identifier for this particular occurrence of the problem.",
+                                    "type": "string"
+                                }
+                            }
+                        }
+                    }
+                }
+                const definitionGenerator = new DefinitionGenerator(mockServerless)
+                let expected = await definitionGenerator.schemaCreator(complexSchema, 'PutRequest')
+                    .catch((err) => {
+                        console.error(err)
+                    })
+
+                expect(definitionGenerator.openAPI.components.schemas).to.have.property('PutRequest')
+                expect(definitionGenerator.openAPI.components.schemas).to.have.property('error')
+                expect(expected).to.equal('#/components/schemas/PutRequest')
+
+                complexSchema.properties.cheese = {
+                    type: 'string'
+                }
+
+                expected = await definitionGenerator.schemaCreator(complexSchema, 'PutRequest')
+                    .catch((err) => {
+                        console.error(err)
+                    })
+
+                expect(definitionGenerator.openAPI.components.schemas).to.have.property('PutRequest')
+                expect(definitionGenerator.openAPI.components.schemas).to.have.property('error')
+
+                let newSchemaStr = expected.split('/')
+                expect(v4.test(newSchemaStr[newSchemaStr.length-1].split('PutRequest-')[1])).to.be.true
+                expect(definitionGenerator.openAPI.components.schemas).to.have.property(newSchemaStr[newSchemaStr.length-1])
+
+                // expected = await definitionGenerator.schemaCreator(complexSchema, 'PutRequest')
+                //     .catch((err) => {
+                //         console.error(err)
+                //     })
+
+                // expect(definitionGenerator.openAPI.components.schemas).to.have.property('PutRequest')
+                // expect(definitionGenerator.openAPI.components.schemas).to.have.property('error')
+                // console.log(expected)
+                // expect(expected)
+                // expect(expected).to.equal('#/components/schemas/PutRequest1')
+
+                complexSchema.properties.wine = {
+                    type: 'string'
+                }
+
+                expected = await definitionGenerator.schemaCreator(complexSchema, 'PutRequest')
+                    .catch((err) => {
+                        console.error(err)
+                    })
+
+                expect(definitionGenerator.openAPI.components.schemas).to.have.property('PutRequest')
+                expect(definitionGenerator.openAPI.components.schemas).to.have.property('error')
+                expect(definitionGenerator.openAPI.components.schemas).to.have.property(newSchemaStr[newSchemaStr.length-1])
+                newSchemaStr = expected.split('/')
+                expect(v4.test(newSchemaStr[newSchemaStr.length-1].split('PutRequest-')[1])).to.be.true
+                expect(definitionGenerator.openAPI.components.schemas).to.have.property(newSchemaStr[newSchemaStr.length-1])
+            });
+
+            it(`should create a new object for a differently named object but with same properties`, async function() {
+                const complexSchema = {
+                    "$schema": "http://json-schema.org/draft-04/schema#",
+                    "title": "JSON API Schema",
+                    "description": "This is a blah blah for responses in the JSON API format. For more, see http://jsonapi.org",
+                    "type": "object",
+                    "required": [
+                        "errors"
+                    ],
+                    "properties": {
+                        "errors": {
+                            "type": "array",
+                            "items": {
+                                "$ref": "#/definitions/error"
+                            },
+                            "uniqueItems": true
+                        }
+                    },
+                    "definitions": {
+                        "error": {
+                            "type": "object",
+                            "properties": {
+                                "id": {
+                                    "description": "A unique identifier for this particular occurrence of the problem.",
+                                    "type": "string"
+                                }
+                            }
+                        }
+                    }
+                }
+                const definitionGenerator = new DefinitionGenerator(mockServerless)
+                let expected = await definitionGenerator.schemaCreator(complexSchema, 'PutRequest')
+                    .catch((err) => {
+                        console.error(err)
+                    })
+
+                expect(definitionGenerator.openAPI.components.schemas).to.have.property('PutRequest')
+                expect(definitionGenerator.openAPI.components.schemas).to.have.property('error')
+                expect(expected).to.equal('#/components/schemas/PutRequest')
+
+                expected = await definitionGenerator.schemaCreator(complexSchema, 'ContactPutRequest')
+                    .catch((err) => {
+                        console.error(err)
+                    })
+
+                expect(definitionGenerator.openAPI.components.schemas).to.have.property('PutRequest')
+                expect(definitionGenerator.openAPI.components.schemas).to.have.property('error')
+                expect(definitionGenerator.openAPI.components.schemas).to.have.property('ContactPutRequest')
+                expect(expected).to.equal('#/components/schemas/ContactPutRequest')
+            });
+
+            it('should not create an object that already references schemas in components', async function() {
+                const simpleSchema = {
+                    "$schema": "http://json-schema.org/draft-04/schema#",
+                    "title": "JSON API Schema",
+                    "description": "This is a blah blah for responses in the JSON API format. For more, see http://jsonapi.org",
+                    "type": "object",
+                    "properties": {
+                        "meta": {
+                            "type": "string",
+
+                        }
+                    }
+                }
+                const definitionGenerator = new DefinitionGenerator(mockServerless)
+                let expected = await definitionGenerator.schemaCreator(simpleSchema, 'meta')
+                    .catch((err) => {
+                        console.error(err)
+                    })
+
+                expect(expected).to.equal('#/components/schemas/meta')
+
+                const complexSchema = {
+                    "$schema": "http://json-schema.org/draft-04/schema#",
+                    "title": "JSON API Schema",
+                    "description": "This is a blah blah for responses in the JSON API format. For more, see http://jsonapi.org",
+                    "type": "object",
+                    "required": [
+                        "errors"
+                    ],
+                    "properties": {
+                        "errors": {
+                            "type": "array",
+                            "items": {
+                                "$ref": "#/definitions/error"
+                            },
+                            "uniqueItems": true
+                        },
+                        "meta": {
+                            "$ref": "#/definitions/meta"
+                        }
+                    },
+                    "definitions": {
+                        "error": {
+                            "type": "object",
+                            "properties": {
+                                "id": {
+                                    "description": "A unique identifier for this particular occurrence of the problem.",
+                                    "type": "string"
+                                }
+                            }
+                        }
+                    }
+                }
+
+                expected = await definitionGenerator.schemaCreator(complexSchema, 'PutRequest')
+                    .catch((err) => {
+                        console.error(err)
+                    })
+
+                expect(definitionGenerator.openAPI.components.schemas).to.have.property('PutRequest')
+                expect(definitionGenerator.openAPI.components.schemas).to.have.property('error')
+                expect(expected).to.equal('#/components/schemas/PutRequest')
+            });
+        });
+
+        describe('schemas that are urls', () => {
+            it('should attempt to download a schema and convert it', async function() {
+                const simpleSchema = 'https:///google.com/build/LicensedMember.json'
+                const LicensedMemberJSON = require('../json/complex.json')
+
+                const stub = sinon.stub($RefParser, 'dereference').resolves(LicensedMemberJSON)
+                const definitionGenerator = new DefinitionGenerator(mockServerless)
+                const expected = await definitionGenerator.schemaCreator(simpleSchema, 'LicensedMember')
+                    .catch((err) => {
+                        console.error(err)
+                    })
+
+                expect(definitionGenerator.openAPI.components.schemas).to.have.property('LicensedMember')
+                expect(definitionGenerator.openAPI.components.schemas).to.have.property('log')
+                expect(definitionGenerator.openAPI.components.schemas).to.have.property('template')
+                expect(definitionGenerator.openAPI.components.schemas).to.have.property('database')
+                expect(expected).to.equal('#/components/schemas/LicensedMember')
+
+                stub.restore()
+            });
+
+            it('should take a mix of schemas', async function() {
+                const complexSchema = 'https:///google.com/build/LicensedMember.json'
+                const LicensedMemberJSON = require('../json/complex.json')
+
+                const stub = sinon.stub($RefParser, 'dereference').resolves(LicensedMemberJSON)
+                const definitionGenerator = new DefinitionGenerator(mockServerless)
+                let expected = await definitionGenerator.schemaCreator(complexSchema, 'LicensedMember')
+                    .catch((err) => {
+                        console.error(err)
+                    })
+
+                const simpleSchema = {
+                    type: "object",
+                    properties: {
+                        UUID: {
+                            $ref: "#/definitions/log"
+                        },
+                        name: {
+                            type: "string"
+                        }
+                    },
+                    definitions: {}
+                }
+
+                expected = await definitionGenerator.schemaCreator(simpleSchema, 'simpleSchema')
+                    .catch((err) => {
+                        console.error(err)
+                    })
+
+                expect(definitionGenerator.openAPI.components.schemas).to.have.property('LicensedMember')
+                expect(definitionGenerator.openAPI.components.schemas).to.have.property('log')
+                expect(definitionGenerator.openAPI.components.schemas).to.have.property('template')
+                expect(definitionGenerator.openAPI.components.schemas).to.have.property('database')
+                expect(definitionGenerator.openAPI.components.schemas).to.have.property('simpleSchema')
+                expect(expected).to.equal('#/components/schemas/simpleSchema')
+
+                stub.restore()
+            });
+
+            it('should throw an error when a url can not be resolved', async function() {
+                const simpleSchema = 'https:///google.com/build/LicensedMember.json'
+
+                const stub = sinon.stub($RefParser, 'dereference').rejects(new Error())
+                const definitionGenerator = new DefinitionGenerator(mockServerless)
+                const expected = await definitionGenerator.schemaCreator(simpleSchema, 'simpleSchema')
+                    .catch((err) => {
+                        console.error(err)
+                    })
+
+                expect(expected).to.be.undefined
+
+                stub.restore()
+            });
+        });
+    });
+});

package/test/unit/openAPIGenerator.spec.js

@@ -0,0 +1,10 @@
+'use strict'
+
+const sinon = require('sinon')
+const expect = require('chai').expect
+
+const OpenAPIGenerator = require('../../src/openAPIGenerator')
+
+xdescribe('OpenAPIGenerator', () => {
+
+});