serverless-openapi-documenter 0.0.23 → 0.0.25

package/README.md

@@ -414,7 +414,7 @@ requestHeaders:
 
 ## Example configuration
 
-Please view the example [serverless.yml](test/serverless\ 2/serverless.yml).
+Please view the example [serverless.yml](test/serverless-tests/serverless%202/serverless.yml).
 
 ## Notes on schemas
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "serverless-openapi-documenter",
-  "version": "0.0.23",
+  "version": "0.0.25",
   "description": "Generate OpenAPI v3 documentation and Postman Collections from your Serverless Config",
   "main": "index.js",
   "keywords": [

package/src/definitionGenerator.js

@@ -79,6 +79,8 @@ class DefinitionGenerator {
                 if (event?.http?.documentation || event?.httpApi?.documentation) {
                     const documentation = event?.http?.documentation || event?.httpApi?.documentation
 
+                    this.currentFunctionName = httpFunction.functionInfo.name
+
                     let opId
                     if (this.operationIds.includes(httpFunction.functionInfo.name) === false) {
                         opId = httpFunction.functionInfo.name
@@ -262,6 +264,8 @@ class DefinitionGenerator {
                 description: response.responseBody.description || '',
             }
 
+            this.currentStatusCode = response.statusCode
+
             obj.content = await this.createMediaTypeObject(response.responseModels, 'responses')
                 .catch(err => {
                     throw err
@@ -290,6 +294,10 @@ class DefinitionGenerator {
     async createMediaTypeObject(models, type) {
         const mediaTypeObj = {}
         for (const mediaTypeDocumentation of this.serverless.service.custom.documentation.models) {
+            if (models === undefined || models === null) {
+                throw new Error(`${this.currentFunctionName} is missing a Response Model for statusCode ${this.currentStatusCode}`)
+            }
+
             if (Object.values(models).includes(mediaTypeDocumentation.name)) {
                 let contentKey = ''
                 for (const [key, value] of Object.entries(models)) {

package/src/openAPIGenerator.js

@@ -107,35 +107,24 @@ class OpenAPIGenerator {
     async generate() {
         this.log(this.defaultLog, chalk.bold.underline('OpenAPI v3 Document Generation'))
         this.processCliInput()
-        const generator = new DefinitionGenerator(this.serverless);
 
-        await generator.parse()
+        const validOpenAPI = await this.generationAndValidation()
           .catch(err => {
-            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', `ERROR: An error was thrown validating the OpenAPI v3 documentation`)
-            throw new this.serverless.classes.Error(err)
-          })
-
-        if (valid)
-          this.log('success', 'OpenAPI v3 Documentation Successfully Generated')
-
         if (this.config.postmanCollection) {
-          this.createPostman(generator.openAPI)
+          this.createPostman(validOpenAPI)
         }
 
         let output
         switch (this.config.format.toLowerCase()) {
           case 'json':
-            output = JSON.stringify(generator.openAPI, null, this.config.indent);
+            output = JSON.stringify(validOpenAPI, null, this.config.indent);
             break;
           case 'yaml':
           default:
-            output = yaml.dump(generator.openAPI, { indent: this.config.indent });
+            output = yaml.dump(validOpenAPI, { indent: this.config.indent });
             break;
         }
         try {
@@ -147,6 +136,28 @@ class OpenAPIGenerator {
         }
     }
 
+    async generationAndValidation() {
+      const generator = new DefinitionGenerator(this.serverless);
+
+      await generator.parse()
+        .catch(err => {
+          this.log('error', `ERROR: An error was thrown generating the OpenAPI v3 documentation`)
+          throw new this.serverless.classes.Error(err)
+        })
+
+      await generator.validate()
+        .catch(err => {
+          this.log('error', `ERROR: An error was thrown validating the OpenAPI v3 documentation`)
+          this.validationErrorDetails(err)
+          throw new this.serverless.classes.Error(err)
+        })
+
+
+      this.log('success', 'OpenAPI v3 Documentation Successfully Generated')
+
+      return generator.openAPI
+    }
+
     createPostman(openAPI) {
       const postmanGeneration = (err, result) => {
         if (err) {
@@ -205,25 +216,10 @@ class OpenAPIGenerator {
       this.config = config
     }
 
-    validateDetails(validation) {
-      if (validation.valid) {
-        this.log(this.defaultLog, `${ chalk.bold.green('[VALIDATION]') } OpenAPI valid: ${chalk.bold.green('true')}\n\n`);
-      } else {
-        this.log(this.defaultLog, `${chalk.bold.red('[VALIDATION]')} Failed to validate OpenAPI document: \n\n`);
-        this.log(this.defaultLog, `${chalk.bold.green('Context:')} ${JSON.stringify(validation.context, null, 2)}\n`);
-        this.log(this.defaultLog, `${chalk.bold.green('Error Message:')} ${JSON.stringify(validation.error, null, 2)}\n`);
-        if (typeof validation.error === 'string') {
-          this.log(this.defaultLog, `${validation.error}\n\n`);
-        } else {
-          for (const info of validation.error) {
-            this.log(this.defaultLog, chalk.grey('\n\n--------\n\n'));
-            this.log(this.defaultLog, ' ', chalk.blue(info.dataPath), '\n');
-            this.log(this.defaultLog, ' ', info.schemaPath, chalk.bold.yellow(info.message));
-            this.log(this.defaultLog, chalk.grey('\n\n--------\n\n'));
-            this.log(this.defaultLog, `${inspect(info, { colors: true, depth: 2 })}\n\n`);
-          }
-        }
-      }
+    validationErrorDetails(validationError) {
+      this.log('error', `${chalk.bold.yellow('[VALIDATION]')} Failed to validate OpenAPI document: \n`);
+      this.log('error', `${chalk.bold.yellow('Context:')} ${JSON.stringify(validationError.options.context[validationError.options.context.length-1], null, 2)}\n`);
+      this.log('error', `${chalk.bold.yellow('Error Message:')} ${JSON.stringify(validationError.message, null, 2)}\n`);
     }
 }
 

package/test/models/BasicDocumentation.json

@@ -0,0 +1,30 @@
+{
+    "custom": {
+        "documentation": {
+            "title": "test-service",
+            "models": [
+                {
+                    "name": "SuccessResponse",
+                    "description": "Success response",
+                    "content": {
+                        "application/json": {
+                            "schema": {
+                                "$schema": "http://json-schema.org/draft-04/schema#",
+                                "properties": {
+                                    "SomeObject": {
+                                        "type": "object",
+                                        "properties": {
+                                            "SomeAttribute": {
+                                                "type": "string"
+                                            }
+                                        }
+                                    }
+                                }
+                            }
+                        }
+                    }
+                }
+            ]
+        }
+    }
+}

package/test/models/BasicValidFunction.json

@@ -0,0 +1,35 @@
+{
+    "createUser": {
+        "name": "createUser",
+        "handler": "handler.create",
+        "events": [
+            {
+                "http": {
+                    "path": "find/{name}",
+                    "method": "get",
+                    "documentation": {
+                        "pathParams": [
+                            {
+                                "name": "name",
+                                "schema": {
+                                    "type": "string"
+                                }
+                            }
+                        ],
+                        "methodResponses": [
+                            {
+                                "statusCode": 200,
+                                "responseBody": {
+                                    "description": "A user object along with generated API Keys"
+                                },
+                                "responseModels": {
+                                    "application/json": "SuccessResponse"
+                                }
+                            }
+                        ]
+                    }
+                }
+            }
+        ]
+    }
+}

package/test/unit/openAPIGenerator.spec.js

@@ -7,12 +7,20 @@ const expect = require('chai').expect
 
 const validOpenAPI = require('../json/valid-openAPI.json')
 
+const basicDocumentation = require('../models/BasicDocumentation.json')
+const basicValidFunction = require('../models/BasicValidFunction.json')
+
 const OpenAPIGenerator = require('../../src/openAPIGenerator')
 
 describe('OpenAPIGenerator', () => {
     let sls, logOutput
     beforeEach(function() {
         sls = {
+            service: {
+                service: 'test-service',
+                getAllFunctions: () => {},
+                getFunction: () => {}
+            },
             version: '3.0.0',
             variables: {
                 service: {
@@ -32,7 +40,7 @@ describe('OpenAPIGenerator', () => {
                 options: {
                     postmanCollection: 'postman.json'
                 }
-            }
+            },
         }
 
         logOutput = {
@@ -43,6 +51,119 @@ describe('OpenAPIGenerator', () => {
             }
         }
     });
+
+    describe('generationAndValidation', () => {
+        it('should correctly generate a valid openAPI document', async function() {
+            const succSpy = sinon.spy(logOutput.log, 'success')
+            const errSpy = sinon.spy(logOutput.log, 'error')
+
+            Object.assign(sls.service, basicDocumentation)
+            const getAllFuncsStub = sinon.stub(sls.service, 'getAllFunctions').returns(['createUser'])
+
+            const getFuncStub = sinon.stub(sls.service, 'getFunction').returns(basicValidFunction.createUser)
+
+            const openAPIGenerator = new OpenAPIGenerator(sls, {}, logOutput)
+            openAPIGenerator.processCliInput()
+
+            const validOpenAPIDocument = await openAPIGenerator.generationAndValidation()
+                .catch(err => {
+                    expect(err).to.be.undefined
+                })
+
+            expect(succSpy.called).to.be.true
+            expect(errSpy.called).to.be.false
+
+            succSpy.restore()
+            errSpy.restore()
+            getAllFuncsStub.reset()
+            getFuncStub.reset()
+        });
+
+        it('should throw an error when trying to generate an invalid openAPI document', async function() {
+            const succSpy = sinon.spy(logOutput.log, 'success')
+            const errSpy = sinon.spy(logOutput.log, 'error')
+
+            Object.assign(sls.service, basicDocumentation)
+            const getAllFuncsStub = sinon.stub(sls.service, 'getAllFunctions').returns(['createUser'])
+            const basicInvalidFunction = JSON.parse(JSON.stringify(basicValidFunction))
+
+            delete basicInvalidFunction.createUser.events[0].http.documentation.methodResponses[0].responseModels
+            const getFuncStub = sinon.stub(sls.service, 'getFunction').returns(basicInvalidFunction.createUser)
+
+            const openAPIGenerator = new OpenAPIGenerator(sls, {}, logOutput)
+            openAPIGenerator.processCliInput()
+
+            const validOpenAPIDocument = await openAPIGenerator.generationAndValidation()
+                .catch(err => {
+                    expect(err.message).to.be.equal('Error: createUser is missing a Response Model for statusCode 200')
+                })
+
+            expect(succSpy.called).to.be.false
+            expect(errSpy.called).to.be.true
+
+            succSpy.restore()
+            errSpy.restore()
+            getAllFuncsStub.reset()
+            getFuncStub.reset()
+        });
+
+        it('should correctly validate a valid openAPI document', async function() {
+            const succSpy = sinon.spy(logOutput.log, 'success')
+            const errSpy = sinon.spy(logOutput.log, 'error')
+
+            Object.assign(sls.service, basicDocumentation)
+            const getAllFuncsStub = sinon.stub(sls.service, 'getAllFunctions').returns(['createUser'])
+            const basicInvalidFunction = JSON.parse(JSON.stringify(basicValidFunction))
+
+            const getFuncStub = sinon.stub(sls.service, 'getFunction').returns(basicInvalidFunction.createUser)
+
+            const openAPIGenerator = new OpenAPIGenerator(sls, {}, logOutput)
+            openAPIGenerator.processCliInput()
+
+            const validOpenAPIDocument = await openAPIGenerator.generationAndValidation()
+                .catch(err => {
+                    expect(err).to.be.undefined
+                })
+
+            expect(succSpy.called).to.be.true
+            expect(errSpy.called).to.be.false
+            expect(validOpenAPIDocument).to.have.property('openapi')
+
+            succSpy.restore()
+            errSpy.restore()
+            getAllFuncsStub.reset()
+            getFuncStub.reset()
+        });
+
+        it('should throw an error when trying to validate an invalid openAPI document', async function() {
+            const succSpy = sinon.spy(logOutput.log, 'success')
+            const errSpy = sinon.spy(logOutput.log, 'error')
+
+            Object.assign(sls.service, basicDocumentation)
+            const getAllFuncsStub = sinon.stub(sls.service, 'getAllFunctions').returns(['createUser'])
+            const basicInvalidFunction = JSON.parse(JSON.stringify(basicValidFunction))
+
+            delete basicInvalidFunction.createUser.events[0].http.documentation.pathParams
+            const getFuncStub = sinon.stub(sls.service, 'getFunction').returns(basicInvalidFunction.createUser)
+
+            const openAPIGenerator = new OpenAPIGenerator(sls, {}, logOutput)
+            openAPIGenerator.processCliInput()
+
+            const validOpenAPIDocument = await openAPIGenerator.generationAndValidation()
+                .catch(err => {
+                    expect(err.message).to.be.equal('AssertionError: Templated parameter name not found')
+                })
+
+            expect(succSpy.called).to.be.false
+            expect(errSpy.called).to.be.true
+
+            succSpy.restore()
+            errSpy.restore()
+            getAllFuncsStub.reset()
+            getFuncStub.reset()
+        });
+    });
+
     describe('createPostman', () => {
         it('should generate a postman collection when a valid openAPI file is generated', function() {
             const fsStub = sinon.stub(fs, 'writeFileSync').returns(true)