serverless-openapi-documenter 0.0.31 → 0.0.33

package/README.md

@@ -59,8 +59,16 @@ Options:
 | info.title               | custom.documentation.title  OR  service                                            |
 | info.description         | custom.documentation.description  OR  blank string                                 |
 | info.version             | custom.documentation.version  OR  random v4 uuid if not provided                   |
+| info.termsOfService      | custom.documentation.termsOfService                                                |
+| info.contact             | custom.documentation.contact                                                       |
+| info.contact.name         | custom.documentation.contact.name OR  blank string                                |
+| info.contact.url          | custom.documentation.contact.url  if provided                                     |
+| info.license             | custom.documentation.license                                                       |
+| info.license.name         | custom.documentation.license.name OR  blank string                                |
+| info.license.url          | custom.documentation.license.url  if provided                                     |
 | externalDocs.description | custom.documentation.externalDocumentation.description                             |
 | externalDocs.url         | custom.documentation.externalDocumentation.url                                     |
+| security                        | custom.documentation.security                                               |
 | servers[].description      | custom.documentation.servers.description                                         |
 | servers[].url              | custom.documentation.servers.url                                                 |
 | servers[].variables              | custom.documentation.servers.variables                                     |
@@ -82,6 +90,7 @@ Options:
 | path[path].[operation].externalDocs.url         | functions.functions.[http OR httpApi].documentation.externalDocumentation.url  |
 | path[path].[operation].servers[].description      | functions.functions.[http OR httpApi].documentation.servers.description      |
 | path[path].[operation].servers[].url              | functions.functions.[http OR httpApi].documentation.servers.url              |
+| path[path].[operation].security              | functions.functions.[http OR httpApi].documentation.security              |
 | path[path].[operation].deprecated         | functions.functions.[http OR httpApi].documentation.deprecated                       |
 | path[path].[operation].parameters         | functions.functions.[http OR httpApi].documentation.[path/query/cookie/header]Params |
 | path[path].[operation].parameters.name         | functions.functions.[http OR httpApi].documentation.[path/query/cookie/header]Params.name |
@@ -118,6 +127,7 @@ custom:
     version: '1'
     title: 'My API'
     description: 'This is my API'
+    termsOfService: https://google.com
     externalDocumentation:
       url: https://google.com
       description: A link to google
@@ -126,7 +136,7 @@ custom:
       description: The server
       variables:
         port:
-          enum: 
+          enum:
             - 4000
             - 3000
           default: 3000
@@ -142,6 +152,58 @@ custom:
 
 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.
 
+#### termsOfService
+
+Must be in the format of a url if included.
+
+#### Contact
+
+You can provide an optional contact object such as:
+
+```yml
+custom:
+  documentation:
+    contact:
+      name: John
+      url: https://example.com
+      email: John@example.com
+```
+
+These fields are optional, though `url` and `email` need to be in the format of an email address (ed: what that might be, i'm not 100% sure... go read the email RFC(s)) and a url.
+
+#### License
+
+You can provide an optional license object such as:
+
+```yml
+custom:
+  documentation:
+    license:
+      name: Apache 2.0
+      url: https://www.apache.org/licenses/LICENSE-2.0.html
+```
+
+Name is required but `url` is optional and must be in the format of a url.
+#### Extended Fields
+
+You can also add extended fields to the documentation object:
+
+```yml
+custom:
+  documentation:
+    x-other-field: This is an extended field
+```
+
+These fields must have `x-` before them, otherwise they will be ignored:
+
+```yml
+custom:
+  documentation:
+    other-field: This is an extended field
+```
+
+`other-field` here will not make it to the generated OpenAPI schema.
+
 These configurations can be quite verbose; you can separate it out into it's own file, such as `serverless.doc.yml` as below:
 
 ```yml
@@ -159,6 +221,40 @@ functions:
 
 For more info on `serverless.yml` syntax, see their docs.
 
+#### securitySchemes
+
+You can provide optional Security Schemes:
+
+```yml
+custom:
+  documentation:
+    securitySchemes:
+      my_api_key:
+        type: apiKey
+        name: api_key
+        in: header
+```
+
+It accepts all available Security Schemes and follows the specification: https://spec.openapis.org/oas/v3.0.3#security-scheme-object
+
+#### Security on each operation
+
+To apply an overall security scheme to all of your operations without having to add the documentation to each one, you can write it like:
+
+```yml
+custom:
+  documentation:
+    securitySchemes:
+      my_api_key:
+        type: apiKey
+        name: api_key
+        in: header
+    security:
+      - my_api_key: []
+```
+
+This will apply the requirement of each operation requiring your `my_api_key` security scheme, [you can override this](#security).
+
 #### 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.
@@ -244,20 +340,20 @@ custom:
         content:
           application/json:
             schema: &ErrorItem
-            type: object
-            properties:
-              message: 
-                type: string
-              code:
-                type: integer
-                  
+              type: object
+              properties:
+                message:
+                  type: string
+                code:
+                  type: integer
+
       - name: "PutDocumentResponse"
         description: "PUT Document response model (external reference example)"
         content:
           application/json:
-            schema: 
-            type: array
-            items: *ErrorItem
+            schema:
+              type: array
+              items: *ErrorItem
 ```
 
 `&ErrorItem` in the above example creates a node anchor (&ErrorItem) to the `ErrorResponse` schema which then can be used in the `PutDocumentResponse` schema via the reference (*ErrorItem).  The node anchor needs to be declared first before it can be used elsewhere via the reference, swapping the above example around would result in an error.
@@ -280,6 +376,7 @@ The `documentation` section of the event configuration can contain the following
 * `pathParams`: a list of path parameters (see [pathParams](#pathparams) below)
 * `cookieParams`: a list of cookie parameters (see [cookieParams](#cookieparams) below)
 * `headerParams`: a list of headers (see [headerParams](#headerparams---request-headers) below)
+* `security`: The security requirement to apply (see [security](#security) below)
 * `methodResponses`: an array of response models and applicable status codes
   * `statusCode`: applicable http status code (ie. 200/404/500 etc.)
   * `responseBody`: contains description of the response
@@ -420,6 +517,62 @@ headerParams:
       type: "string"
 ```
 
+#### `security`
+
+The `security` property allows you to specify the [Security Scheme](#securityschemes) to apply to the HTTP Request.  If you have applied an `security` ([see Security on each operation](#security-on-each-operation)) then you can either leave this field off, or to override it with a different scheme you can write it like:
+
+```yml
+custom:
+  documentation:
+    securitySchemes:
+      my_api_key:
+        type: apiKey
+        name: api_key
+        in: header
+      petstore_auth:
+        type: oauth2
+        flows:
+          implicit:
+            authorizationUrl: https://example.com/api/oauth/dialog
+            scopes:
+              write:pets: modify pets in your account
+              read:pets: read your pets
+    security:
+      - my_api_key: []
+
+functions:
+  getData:
+    events:
+      - http:
+          documentation:
+            security:
+              - petstore_auth:
+                - write:pets
+                - read:pets
+```
+
+If you have specified an `security` at the document root, but this HTTP Request should not apply any security schemes, you should set security to be an array with an empty object:
+
+```yml
+custom:
+  documentation:
+    securitySchemes:
+      my_api_key:
+        type: apiKey
+        name: api_key
+        in: header
+    security:
+      - my_api_key: []
+
+functions:
+  getData:
+    events:
+      - http:
+          documentation:
+            security:
+              - {}
+```
+
 #### `requestModels`
 
 The `requestModels` property allows you to define models for the HTTP Request of the function event. You can define a different model for each different `Content-Type`. You can define a reference to the relevant request model named in the `models` section of your configuration (see [Defining Models](#models) section).

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "serverless-openapi-documenter",
-  "version": "0.0.31",
+  "version": "0.0.33",
   "description": "Generate OpenAPI v3 documentation and Postman Collections from your Serverless Config",
   "main": "index.js",
   "keywords": [
@@ -42,7 +42,7 @@
   },
   "devDependencies": {
     "chai": "^4.3.7",
-    "mocha": "^10.1.0",
+    "mocha": "^10.2.0",
     "sinon": "^15.0.0"
   }
 }

package/src/definitionGenerator.js

@@ -39,6 +39,15 @@ class DefinitionGenerator {
 
     async parse() {
         this.createInfo()
+
+        if (this.serverless.service.custom.documentation.securitySchemes) {
+            this.createSecuritySchemes(this.serverless.service.custom.documentation.securitySchemes)
+
+            if (this.serverless.service.custom.documentation.security) {
+                this.openAPI.security = this.serverless.service.custom.documentation.security
+            }
+        }
+
         await this.createPaths()
             .catch(err => {
                 throw err
@@ -68,6 +77,37 @@ class DefinitionGenerator {
             description: documentation?.description || '',
             version: documentation?.version || uuid(),
         }
+
+        if (documentation.termsOfService)
+            info.termsOfService = documentation.termsOfService
+
+        if (documentation.contact) {
+            const contactObj = {}
+            contactObj.name = documentation.contact.name || ''
+
+            if (documentation.contact.url)
+                contactObj.url = documentation.contact.url
+
+            contactObj.email = documentation.contact.email || ''
+            Object.assign(info, {contact: contactObj})
+        }
+
+        if (documentation.license && documentation.license.name) {
+            const licenseObj = {}
+            licenseObj.name = documentation.license.name || ''
+
+            if (documentation.license.url)
+                licenseObj.url = documentation.license.url || ''
+
+            Object.assign(info, {license: licenseObj})
+        }
+
+        for (const key of Object.keys(documentation)) {
+            if (/^[x\-]/i.test(key)) {
+                Object.assign(info, {[key]: documentation[key]})
+            }
+        }
+
         Object.assign(this.openAPI, {info})
     }
 
@@ -234,6 +274,10 @@ class DefinitionGenerator {
             obj.externalDocs = documentation.externalDocumentation
         }
 
+        if (Object.keys(documentation).includes('security')) {
+            obj.security = documentation.security
+        }
+
         if (Object.keys(documentation).includes('deprecated'))
             obj.deprecated = documentation.deprecated
 
@@ -492,6 +536,146 @@ class DefinitionGenerator {
         }
     }
 
+    addToComponents(type, schema, name) {
+        const schemaObj = {
+            [name]: schema
+        }
+
+        if (this.openAPI?.components) {
+            if (this.openAPI.components[type]) {
+                Object.assign(this.openAPI.components[type], schemaObj)
+            } else {
+                Object.assign(this.openAPI.components, {[type]: schemaObj})
+            }
+        } else {
+            const components = {
+                components: {
+                    [type]: schemaObj
+                }
+            }
+
+            Object.assign(this.openAPI, components)
+        }
+    }
+
+    createSecuritySchemes(securitySchemes) {
+        for (const scheme of Object.keys(securitySchemes)) {
+            const securityScheme = securitySchemes[scheme]
+            const schema = {}
+
+            if (securityScheme.description)
+                schema.description = securityScheme.description
+
+            switch(securityScheme.type.toLowerCase()) {
+                case 'apikey':
+                    const apiKeyScheme = this.createAPIKeyScheme(securityScheme)
+                    schema.type = 'apiKey'
+                    Object.assign(schema, apiKeyScheme)
+                break;
+
+                case 'http':
+                    const HTTPScheme = this.createHTTPScheme(securityScheme)
+                    schema.type = 'http'
+                    Object.assign(schema, HTTPScheme)
+                break;
+
+                case 'openidconnect':
+                    const openIdConnectScheme = this.createOpenIDConnectScheme(securityScheme)
+                    schema.type = 'openIdConnect'
+                    Object.assign(schema, openIdConnectScheme)
+                break;
+
+                case 'oauth2':
+                    const oAuth2Scheme = this.createOAuth2Scheme(securityScheme)
+                    schema.type = 'oauth2'
+                    Object.assign(schema, oAuth2Scheme)
+                break;
+            }
+
+            this.addToComponents('securitySchemes', schema, scheme)
+        }
+    }
+
+    createAPIKeyScheme(securitySchema) {
+        const schema = {}
+        if (securitySchema.name)
+            schema.name = securitySchema.name
+        else
+            throw new Error('Security Scheme for "apiKey" requires the name of the header, query or cookie parameter to be used')
+
+        if (securitySchema.in)
+            schema.in = securitySchema.in
+        else
+            throw new Error('Security Scheme for "apiKey" requires the location of the API key: header, query or cookie parameter')
+
+        return schema
+    }
+
+    createHTTPScheme(securitySchema) {
+        const schema = {}
+
+        if (securitySchema.scheme)
+            schema.scheme = securitySchema.scheme
+        else
+            throw new Error('Security Scheme for "http" requires scheme')
+
+        if (securitySchema.bearerFormat)
+            schema.bearerFormat = securitySchema.bearerFormat
+
+        return schema
+    }
+
+    createOpenIDConnectScheme(securitySchema) {
+        const schema = {}
+        if (securitySchema.openIdConnectUrl)
+            schema.openIdConnectUrl = securitySchema.openIdConnectUrl
+        else
+            throw new Error('Security Scheme for "openIdConnect" requires openIdConnectUrl')
+
+        return schema
+    }
+
+    createOAuth2Scheme(securitySchema) {
+        const schema = {}
+        if (securitySchema.flows) {
+            const flows = this.createOAuthFlows(securitySchema.flows)
+            Object.assign(schema, {flows: flows})
+        } else
+            throw new Error('Security Scheme for "oauth2" requires flows')
+
+        return schema
+    }
+
+    createOAuthFlows(flows) {
+        const obj = {}
+        for (const flow of Object.keys(flows)) {
+            const schema = {}
+            if (["implicit", 'authorizationCode'].includes(flow))
+                if (flows[flow].authorizationUrl)
+                    schema.authorizationUrl = flows[flow].authorizationUrl
+                else
+                    throw new Error(`oAuth2 ${flow} flow requires an authorizationUrl`)
+
+            if (['password', 'clientCredentials', 'authorizationCode'].includes(flow)) {
+                if (flows[flow].tokenUrl)
+                    schema.tokenUrl = flows[flow].tokenUrl
+                else
+                    throw new Error(`oAuth2 ${flow} flow requires a tokenUrl`)
+            }
+
+            if (flows[flow].refreshUrl)
+                schema.refreshUrl = flows[flow].refreshUrl
+
+            if (flows[flow].scopes)
+                schema.scopes = flows[flow].scopes
+            else
+                throw new Error(`oAuth2 ${flow} flow requires scopes`)
+
+            Object.assign(obj, {[flow]: schema})
+        }
+        return obj
+    }
+
     createExamples(examples) {
         const examplesObj = {}
 

package/test/unit/definitionGenerator.spec.js

@@ -3,7 +3,7 @@
 const fs = require('fs').promises
 const path = require('path')
 const sinon = require('sinon')
-const $RefParser = require("@apidevtools/json-schema-ref-parser");
+const $RefParser = require("@apidevtools/json-schema-ref-parser")
 const expect = require('chai').expect
 
 const serverlessMock = require('../helpers/serverless')
@@ -174,6 +174,482 @@ describe('DefinitionGenerator', () => {
             expect(definitionGenerator.openAPI.info).to.be.an('object')
             expect(v4.test(definitionGenerator.openAPI.info.version)).to.be.true
         });
+
+        it('should assign a contact Object when a contact object is included', function() {
+            mockServerless.service.custom.documentation.contact = {
+                name: 'John',
+                url: 'http://example.com',
+                email: 'john@example.com'
+            }
+            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.have.property('contact')
+            expect(definitionGenerator.openAPI.info.contact).to.be.an('object')
+            expect(definitionGenerator.openAPI.info.contact.name).to.be.an('string')
+        });
+
+        it('should only assign a contact url if one is provided', function() {
+            mockServerless.service.custom.documentation.contact = {
+                name: 'John',
+                email: 'john@example.com'
+            }
+            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.have.property('contact')
+            expect(definitionGenerator.openAPI.info.contact).to.be.an('object')
+            expect(definitionGenerator.openAPI.info.contact.name).to.be.an('string')
+            expect(definitionGenerator.openAPI.info.contact).to.not.have.property('url')
+        });
+
+        it('should assign a license Object when a license object is included with a name', function() {
+            mockServerless.service.custom.documentation.license = {
+                name: 'Apache 2.0',
+                url: 'https://www.apache.org/licenses/LICENSE-2.0.html',
+            }
+            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.have.property('license')
+            expect(definitionGenerator.openAPI.info.license).to.be.an('object')
+            expect(definitionGenerator.openAPI.info.license.name).to.be.an('string')
+        });
+
+        it('should not assign a license Object when a license object is included without a name', function() {
+            mockServerless.service.custom.documentation.license = {
+                url: 'https://www.apache.org/licenses/LICENSE-2.0.html',
+            }
+            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.not.have.property('license')
+        });
+
+        it('should only assign a contact url if one is provided', function() {
+            mockServerless.service.custom.documentation.license = {
+                name: 'John',
+            }
+            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.have.property('license')
+            expect(definitionGenerator.openAPI.info.license).to.be.an('object')
+            expect(definitionGenerator.openAPI.info.license.name).to.be.an('string')
+            expect(definitionGenerator.openAPI.info.license).to.not.have.property('url')
+        });
+
+        it('should assign specification extension fields when included', function() {
+            mockServerless.service.custom.documentation['x-field'] = 'john'
+            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.have.property('x-field')
+            expect(definitionGenerator.openAPI.info['x-field']).to.be.equal('john')
+        });
+
+        it('should ignore fields that do not conform to specifiction extension', function() {
+            mockServerless.service.custom.documentation.otherField = 'john'
+            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.not.have.property('otherField')
+        });
+    });
+
+    describe('createSecuritySchemes', () => {
+        describe('API Keys', () => {
+            it('should add an API Key security scheme to components', function() {
+                mockServerless.service.custom.documentation.securitySchemes = {
+                    'api_key': {
+                        type: 'apiKey',
+                        name: 'Authorization',
+                        in: 'header'
+                    }
+                }
+
+                const definitionGenerator = new DefinitionGenerator(mockServerless)
+                definitionGenerator.createSecuritySchemes(mockServerless.service.custom.documentation.securitySchemes)
+
+                expect(definitionGenerator.openAPI).to.be.an('object')
+                expect(definitionGenerator.openAPI.components).to.be.an('object')
+                expect(definitionGenerator.openAPI.components).to.have.property('securitySchemes')
+                expect(definitionGenerator.openAPI.components.securitySchemes).to.be.an('object')
+                expect(definitionGenerator.openAPI.components.securitySchemes).to.have.property('api_key')
+                expect(definitionGenerator.openAPI.components.securitySchemes.api_key).to.have.property('type')
+                expect(definitionGenerator.openAPI.components.securitySchemes.api_key.type).to.be.equal('apiKey')
+            });
+
+            it('should throw an error when name is missing from an API Key scheme', function() {
+                mockServerless.service.custom.documentation.securitySchemes = {
+                    'api_key': {
+                        type: 'apiKey',
+                        in: 'header'
+                    }
+                }
+
+                const definitionGenerator = new DefinitionGenerator(mockServerless)
+                expect(() => {
+                    definitionGenerator.createSecuritySchemes(mockServerless.service.custom.documentation.securitySchemes)
+                }).to.throw('Security Scheme for "apiKey" requires the name of the header, query or cookie parameter to be used')
+            });
+
+            it('should throw an error when in is missing from an API Key scheme', function() {
+                mockServerless.service.custom.documentation.securitySchemes = {
+                    'api_key': {
+                        type: 'apiKey',
+                        name: 'Authorization',
+                    }
+                }
+
+                const definitionGenerator = new DefinitionGenerator(mockServerless)
+                expect(() => {
+                    definitionGenerator.createSecuritySchemes(mockServerless.service.custom.documentation.securitySchemes)
+                }).to.throw('Security Scheme for "apiKey" requires the location of the API key: header, query or cookie parameter')
+            });
+        });
+
+        describe('HTTP', () => {
+            it('should add an HTTP security scheme to components', function() {
+                mockServerless.service.custom.documentation.securitySchemes = {
+                    'http_key': {
+                        type: 'http',
+                        scheme: 'basic'
+                    }
+                }
+
+                const definitionGenerator = new DefinitionGenerator(mockServerless)
+                definitionGenerator.createSecuritySchemes(mockServerless.service.custom.documentation.securitySchemes)
+
+                expect(definitionGenerator.openAPI).to.be.an('object')
+                expect(definitionGenerator.openAPI.components).to.be.an('object')
+                expect(definitionGenerator.openAPI.components).to.have.property('securitySchemes')
+                expect(definitionGenerator.openAPI.components.securitySchemes).to.be.an('object')
+                expect(definitionGenerator.openAPI.components.securitySchemes).to.have.property('http_key')
+            });
+
+            it('should throw an error when scheme is missing from an HTTP scheme', function() {
+                mockServerless.service.custom.documentation.securitySchemes = {
+                    'http_key': {
+                        type: 'http',
+                    }
+                }
+
+                const definitionGenerator = new DefinitionGenerator(mockServerless)
+                expect(() => {
+                    definitionGenerator.createSecuritySchemes(mockServerless.service.custom.documentation.securitySchemes)
+                }).to.throw('Security Scheme for "http" requires scheme')
+            });
+        });
+
+        describe('openIdConnect', () => {
+            it('should add an openIdConnect security scheme to components', function() {
+                mockServerless.service.custom.documentation.securitySchemes = {
+                    'openIdConnect_key': {
+                        type: 'openIdConnect',
+                        openIdConnectUrl: 'http://example.com'
+                    }
+                }
+
+                const definitionGenerator = new DefinitionGenerator(mockServerless)
+                definitionGenerator.createSecuritySchemes(mockServerless.service.custom.documentation.securitySchemes)
+
+                expect(definitionGenerator.openAPI).to.be.an('object')
+                expect(definitionGenerator.openAPI.components).to.be.an('object')
+                expect(definitionGenerator.openAPI.components).to.have.property('securitySchemes')
+                expect(definitionGenerator.openAPI.components.securitySchemes).to.be.an('object')
+                expect(definitionGenerator.openAPI.components.securitySchemes).to.have.property('openIdConnect_key')
+            });
+
+            it('should throw an error when openIdConnectUrl is missing from an openIdConnect scheme', function() {
+                mockServerless.service.custom.documentation.securitySchemes = {
+                    'openIdConnect_key': {
+                        type: 'openIdConnect',
+                    }
+                }
+
+                const definitionGenerator = new DefinitionGenerator(mockServerless)
+                expect(() => {
+                    definitionGenerator.createSecuritySchemes(mockServerless.service.custom.documentation.securitySchemes)
+                }).to.throw('Security Scheme for "openIdConnect" requires openIdConnectUrl')
+            });
+        });
+
+        describe('oauth2', () => {
+            it('should add an oauth2 security scheme to components', function() {
+                mockServerless.service.custom.documentation.securitySchemes = {
+                    'oAuth2_key': {
+                        type: 'oauth2',
+                        flows: {
+                            implicit: {
+                                authorizationUrl: 'http://example.org/api/oauth/dialog',
+                                scopes: {
+                                    'write:pets': 'modify pets in your account',
+                                    'read:pets': 'read your pets'
+                                }
+                            }
+                        }
+                    }
+                }
+
+                const definitionGenerator = new DefinitionGenerator(mockServerless)
+                definitionGenerator.createSecuritySchemes(mockServerless.service.custom.documentation.securitySchemes)
+
+                expect(definitionGenerator.openAPI).to.be.an('object')
+                expect(definitionGenerator.openAPI.components).to.be.an('object')
+                expect(definitionGenerator.openAPI.components).to.have.property('securitySchemes')
+                expect(definitionGenerator.openAPI.components.securitySchemes).to.be.an('object')
+                expect(definitionGenerator.openAPI.components.securitySchemes).to.have.property('oAuth2_key')
+                expect(definitionGenerator.openAPI.components.securitySchemes.oAuth2_key).to.be.an('object')
+                expect(definitionGenerator.openAPI.components.securitySchemes.oAuth2_key).to.have.property('type')
+                expect(definitionGenerator.openAPI.components.securitySchemes.oAuth2_key).to.have.property('flows')
+                expect(definitionGenerator.openAPI.components.securitySchemes.oAuth2_key.flows).to.be.an('object')
+                expect(definitionGenerator.openAPI.components.securitySchemes.oAuth2_key.flows).to.have.property('implicit')
+                expect(definitionGenerator.openAPI.components.securitySchemes.oAuth2_key.flows.implicit).to.be.an('object')
+                expect(definitionGenerator.openAPI.components.securitySchemes.oAuth2_key.flows.implicit).to.have.property('scopes')
+                expect(definitionGenerator.openAPI.components.securitySchemes.oAuth2_key.flows.implicit.scopes).to.be.an('object')
+            });
+
+            it('should throw an error when flows is missing from an oauth2 scheme', function() {
+                mockServerless.service.custom.documentation.securitySchemes = {
+                    'oAuth2_key': {
+                        type: 'oauth2',
+                    }
+                }
+
+                const definitionGenerator = new DefinitionGenerator(mockServerless)
+                expect(() => {
+                    definitionGenerator.createSecuritySchemes(mockServerless.service.custom.documentation.securitySchemes)
+                }).to.throw('Security Scheme for "oauth2" requires flows')
+            });
+
+            it('should throw an error when authorizationUrl is missing from an oauth2 implicit flow scheme', function() {
+                mockServerless.service.custom.documentation.securitySchemes = {
+                    'oAuth2_key': {
+                        type: 'oauth2',
+                        flows: {
+                            implicit: {
+                                scopes: {
+                                    'write:pets': 'modify pets in your account',
+                                    'read:pets': 'read your pets'
+                                }
+                            }
+                        }
+                    }
+                }
+
+                const definitionGenerator = new DefinitionGenerator(mockServerless)
+                expect(() => {
+                    definitionGenerator.createSecuritySchemes(mockServerless.service.custom.documentation.securitySchemes)
+                }).to.throw('oAuth2 implicit flow requires an authorizationUrl')
+            });
+
+            it('should throw an error when authorizationUrl is missing from an oauth2 authorizationCode flow scheme', function() {
+                mockServerless.service.custom.documentation.securitySchemes = {
+                    'oAuth2_key': {
+                        type: 'oauth2',
+                        flows: {
+                            authorizationCode: {
+                                tokenUrl: 'http://example.com',
+                                scopes: {
+                                    'write:pets': 'modify pets in your account',
+                                    'read:pets': 'read your pets'
+                                }
+                            }
+                        }
+                    }
+                }
+
+                const definitionGenerator = new DefinitionGenerator(mockServerless)
+                expect(() => {
+                    definitionGenerator.createSecuritySchemes(mockServerless.service.custom.documentation.securitySchemes)
+                }).to.throw('oAuth2 authorizationCode flow requires an authorizationUrl')
+            });
+
+            it('should throw an error when tokenUrl is missing from an oauth2 authorizationCode flow scheme', function() {
+                mockServerless.service.custom.documentation.securitySchemes = {
+                    'oAuth2_key': {
+                        type: 'oauth2',
+                        flows: {
+                            authorizationCode: {
+                                authorizationUrl: 'http://example.org/api/oauth/dialog',
+                                scopes: {
+                                    'write:pets': 'modify pets in your account',
+                                    'read:pets': 'read your pets'
+                                }
+                            }
+                        }
+                    }
+                }
+
+                const definitionGenerator = new DefinitionGenerator(mockServerless)
+                expect(() => {
+                    definitionGenerator.createSecuritySchemes(mockServerless.service.custom.documentation.securitySchemes)
+                }).to.throw('oAuth2 authorizationCode flow requires a tokenUrl')
+            });
+
+            it('should throw an error when tokenUrl is missing from an oauth2 password flow scheme', function() {
+                mockServerless.service.custom.documentation.securitySchemes = {
+                    'oAuth2_key': {
+                        type: 'oauth2',
+                        flows: {
+                            password: {
+                                scopes: {
+                                    'write:pets': 'modify pets in your account',
+                                    'read:pets': 'read your pets'
+                                }
+                            }
+                        }
+                    }
+                }
+
+                const definitionGenerator = new DefinitionGenerator(mockServerless)
+                expect(() => {
+                    definitionGenerator.createSecuritySchemes(mockServerless.service.custom.documentation.securitySchemes)
+                }).to.throw('oAuth2 password flow requires a tokenUrl')
+            });
+
+            it('should throw an error when tokenUrl is missing from an oauth2 clientCredentials flow scheme', function() {
+                mockServerless.service.custom.documentation.securitySchemes = {
+                    'oAuth2_key': {
+                        type: 'oauth2',
+                        flows: {
+                            clientCredentials: {
+                                scopes: {
+                                    'write:pets': 'modify pets in your account',
+                                    'read:pets': 'read your pets'
+                                }
+                            }
+                        }
+                    }
+                }
+
+                const definitionGenerator = new DefinitionGenerator(mockServerless)
+                expect(() => {
+                    definitionGenerator.createSecuritySchemes(mockServerless.service.custom.documentation.securitySchemes)
+                }).to.throw('oAuth2 clientCredentials flow requires a tokenUrl')
+            });
+
+            it('should throw an error when scopes is missing from an oauth2 clientCredentials flow scheme', function() {
+                mockServerless.service.custom.documentation.securitySchemes = {
+                    'oAuth2_key': {
+                        type: 'oauth2',
+                        flows: {
+                            clientCredentials: {
+                                tokenUrl: 'http://example.com',
+                            }
+                        }
+                    }
+                }
+
+                const definitionGenerator = new DefinitionGenerator(mockServerless)
+                expect(() => {
+                    definitionGenerator.createSecuritySchemes(mockServerless.service.custom.documentation.securitySchemes)
+                }).to.throw('oAuth2 clientCredentials flow requires scopes')
+            });
+
+            it('should throw an error when scopes is missing from an oauth2 authorizationCode flow scheme', function() {
+                mockServerless.service.custom.documentation.securitySchemes = {
+                    'oAuth2_key': {
+                        type: 'oauth2',
+                        flows: {
+                            authorizationCode: {
+                                tokenUrl: 'http://example.com',
+                                authorizationUrl: 'http://example.org/api/oauth/dialog',
+                            }
+                        }
+                    }
+                }
+
+                const definitionGenerator = new DefinitionGenerator(mockServerless)
+                expect(() => {
+                    definitionGenerator.createSecuritySchemes(mockServerless.service.custom.documentation.securitySchemes)
+                }).to.throw('oAuth2 authorizationCode flow requires scopes')
+            });
+
+            it('should throw an error when scopes is missing from an oauth2 password flow scheme', function() {
+                mockServerless.service.custom.documentation.securitySchemes = {
+                    'oAuth2_key': {
+                        type: 'oauth2',
+                        flows: {
+                            password: {
+                                tokenUrl: 'http://example.com',
+                            }
+                        }
+                    }
+                }
+
+                const definitionGenerator = new DefinitionGenerator(mockServerless)
+                expect(() => {
+                    definitionGenerator.createSecuritySchemes(mockServerless.service.custom.documentation.securitySchemes)
+                }).to.throw('oAuth2 password flow requires scopes')
+            });
+
+            it('should throw an error when scopes is missing from an oauth2 implicit flow scheme', function() {
+                mockServerless.service.custom.documentation.securitySchemes = {
+                    'oAuth2_key': {
+                        type: 'oauth2',
+                        flows: {
+                            implicit: {
+                                authorizationUrl: 'http://example.org/api/oauth/dialog',
+                            }
+                        }
+                    }
+                }
+
+                const definitionGenerator = new DefinitionGenerator(mockServerless)
+                expect(() => {
+                    definitionGenerator.createSecuritySchemes(mockServerless.service.custom.documentation.securitySchemes)
+                }).to.throw('oAuth2 implicit flow requires scopes')
+            });
+        });
+
+        describe('Multiple Schemes', () => {
+            it('should add an oauth2 and an apiKey security scheme to components', function() {
+                mockServerless.service.custom.documentation.securitySchemes = {
+                    'oAuth2_key': {
+                        type: 'oauth2',
+                        flows: {
+                            implicit: {
+                                authorizationUrl: 'http://example.org/api/oauth/dialog',
+                                scopes: {
+                                    'write:pets': 'modify pets in your account',
+                                    'read:pets': 'read your pets'
+                                }
+                            }
+                        }
+                    },
+                    'api_key': {
+                        type: 'apiKey',
+                        name: 'Authorization',
+                        in: 'header'
+                    }
+                }
+
+                const definitionGenerator = new DefinitionGenerator(mockServerless)
+                definitionGenerator.createSecuritySchemes(mockServerless.service.custom.documentation.securitySchemes)
+                expect(definitionGenerator.openAPI).to.be.an('object')
+                expect(definitionGenerator.openAPI.components).to.be.an('object')
+                expect(definitionGenerator.openAPI.components).to.have.property('securitySchemes')
+                expect(definitionGenerator.openAPI.components.securitySchemes).to.be.an('object')
+                expect(definitionGenerator.openAPI.components.securitySchemes).to.have.property('oAuth2_key')
+                expect(definitionGenerator.openAPI.components.securitySchemes).to.have.property('api_key')
+            });
+        });
     });
 
     describe('createTags', () => {