serverless-openapi-documenter 0.0.24 → 0.0.26

package/README.md

@@ -350,6 +350,24 @@ cookieParams:
       type: "string"
 ```
 
+#### `headerParams` - Request Headers
+
+Request Headers can be described as follow:
+
+* `name`: the name of the query variable
+* `description`: a description of the query variable
+* `required`: whether the query parameter is mandatory (boolean)
+* `schema`: JSON schema (inline, file or externally hosted)
+
+```yml
+headerParams:
+  - name: "Content-Type"
+    description: "The content type"
+    required: true
+    schema:
+      type: "string"
+```
+
 #### `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).
@@ -369,14 +387,24 @@ For an example of a `methodResponses` configuration for an event see below:
 ```yml
 methodResponse:
   - statusCode: 200
-    responseHeaders:
-      - name: "Content-Type"
-        description: "Content Type header"
-        schema:
-          type: "string"
+    responseBody:
+      description: Success
     responseModels:
       application/json: "CreateResponse"
       application/xml: "CreateResponseXML"
+    responseHeaders:
+      X-Rate-Limit-Limit:
+        description: The number of allowed requests in the current period
+        schema:
+          type: integer
+      X-Rate-Limit-Remaining:
+        description: The number of remaining requests in the current period
+        schema:
+          type: integer
+      X-Rate-Limit-Reset:
+        description: The number of seconds left in the current period
+        schema:
+          type: integer
 ```
 
 ##### `responseModels`
@@ -389,27 +417,16 @@ responseModels:
   application/xml: "CreateResponseXML"
 ```
 
-##### `responseHeaders` and `requestHeaders`
-
-The `responseHeaders/requestHeaders` section of the configuration allows you to define the HTTP headers for the function event.
+##### `responseHeaders`
 
-The attributes for a header are as follow:
-
-* `name`: the name of the HTTP Header
-* `description`: a description of the HTTP Header
-* `schema`: JSON schema (inline, file or externally hosted)
+The `responseHeaders` property allows you to define the headers expected in a HTTP Response of the function event.  This should only contain a description and a schema, which must be a JSON schema (inline, file or externally hosted).
 
 ```yml
 responseHeaders:
-  - name: "Content-Type"
-    description: "Content Type header"
+  X-Rate-Limit-Limit:
+    description: The number of allowed requests in the current period
     schema:
-      type: "string"
-requestHeaders:
-  - name: "Content-Type"
-    description: "Content Type header"
-    schema:
-      type: "string"
+      type: integer
 ```
 
 ## Example configuration

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "serverless-openapi-documenter",
-  "version": "0.0.24",
+  "version": "0.0.26",
   "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,17 +264,48 @@ class DefinitionGenerator {
                 description: response.responseBody.description || '',
             }
 
+            this.currentStatusCode = response.statusCode
+
             obj.content = await this.createMediaTypeObject(response.responseModels, 'responses')
                 .catch(err => {
                     throw err
                 })
 
+            if (response.responseHeaders) {
+                obj.headers = await this.createResponseHeaders(response.responseHeaders)
+                    .catch(err => {
+                        throw err
+                    })
+            }
+
             Object.assign(responses,{[response.statusCode]: obj})
         }
 
         return responses
     }
 
+    async createResponseHeaders(headers) {
+        const obj = {}
+        for (const header of Object.keys(headers)) {
+            const newHeader = {}
+            newHeader.description = headers[header].description || ''
+
+            if (headers[header].schema) {
+                const schemaRef = await this.schemaCreator(headers[header].schema, header)
+                    .catch(err => {
+                        throw err
+                    })
+                newHeader.schema = {
+                    $ref: schemaRef
+                }
+            }
+
+            Object.assign(obj, {[header]: newHeader})
+        }
+
+        return obj
+    }
+
     async createRequestBody(documentation) {
         const obj = {
             description: documentation.requestBody.description,
@@ -290,6 +323,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)