serverless-openapi-documenter 0.0.49 → 0.0.51

package/README.md

@@ -403,6 +403,7 @@ functions:
       - http:
         path: create
         method: post
+        cors: true
         summary:
         documentation:
           summary: "Create User"
@@ -645,6 +646,12 @@ responseHeaders:
       type: integer
 ```
 
+###### CORS
+
+You can automatically generate CORS response headers by setting `cors` at the function level.  Serverless allows you to modify how CORS is setup, so you can have the default options with `cors: true`, or you can modify the settings as shown in the [serverless documentation for CORS](https://www.serverless.com/framework/docs/providers/aws/events/apigateway#enabling-cors).
+
+The generator will interpret your settings for CORS and automatically add the response headers.  If for whatever reason you wish to override these, you can set them via the above `responseHeaders` setting and it'll apply your overrides.
+
 ## Example configuration
 
 Please view the example [serverless.yml](test/serverless-tests/serverless%202/serverless.yml).

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "serverless-openapi-documenter",
-  "version": "0.0.49",
+  "version": "0.0.51",
   "description": "Generate OpenAPI v3 documentation and Postman Collections from your Serverless Config",
   "main": "index.js",
   "keywords": [
@@ -38,7 +38,7 @@
     "json-schema-for-openapi": "^0.3.2",
     "lodash.isequal": "^4.5.0",
     "oas-validator": "^5.0.8",
-    "openapi-to-postmanv2": "^4.11.0",
+    "openapi-to-postmanv2": "^4.12.0",
     "swagger2openapi": "^7.0.8",
     "uuid": "^9.0.0"
   },

package/src/definitionGenerator.js

@@ -35,6 +35,24 @@ class DefinitionGenerator {
             securitySchemes: 'securitySchemes'
         }
 
+        this.DEFAULT_CORS_HEADERS = {
+            'Access-Control-Allow-Origin': {
+                description: 'The Access-Control-Allow-Origin response header indicates whether the response can be shared with requesting code from the given origin.',
+                schema: {
+                    type: 'string',
+                    default: '*',
+                    example: 'https://developer.mozilla.org'
+                }
+            },
+            'Access-Control-Allow-Credentials': {
+                description: `The Access-Control-Allow-Credentials response header tells browsers whether to expose the response to the frontend JavaScript code when the request's credentials mode (Request.credentials) is include`,
+                schema: {
+                    type: 'boolean',
+                    default: true
+                }
+            }
+        }
+
         try {
             this.refParserOptions = require(path.resolve('options', 'ref-parser.js'))
         } catch (err) {
@@ -123,6 +141,7 @@ class DefinitionGenerator {
         for (const httpFunction of httpFunctions) {
             for (const event of httpFunction.event) {
                 if (event?.http?.documentation || event?.httpApi?.documentation) {
+                    this.currentEvent = event?.http || event?.httpApi
                     const documentation = event?.http?.documentation || event?.httpApi?.documentation
 
                     this.currentFunctionName = httpFunction.functionInfo.name
@@ -328,14 +347,68 @@ class DefinitionGenerator {
                     })
             }
 
+
+            const corsHeaders = await this.corsHeaders()
+                .catch(err => {
+                    throw err;
+                })
+
+            if (obj.headers) {
+                for (const key in corsHeaders) {
+                    if (!(key in obj.headers) && (obj.headers[key] = {})) {
+                        obj.headers[key] = corsHeaders[key]
+                    }
+                }
+            } else {
+                obj.headers = corsHeaders
+            }
+
             Object.assign(responses,{[response.statusCode]: obj})
         }
 
         return responses
     }
 
+    async corsHeaders() {
+        let headers = {}
+        if (this.currentEvent?.cors === true) {
+            headers = await this.createResponseHeaders(this.DEFAULT_CORS_HEADERS)
+                .catch(err => {
+                    throw err;
+                })
+        } else if (this.currentEvent.cors) {
+            const newHeaders = {}
+            for (const key of Object.keys(this.DEFAULT_CORS_HEADERS)) {
+                if (key === 'Access-Control-Allow-Credentials' &&
+                    this.currentEvent.cors.allowCredentials === undefined || this.currentEvent.cors?.allowCredentials === false) {
+                    continue
+                }
+
+                const obj = JSON.parse(JSON.stringify(this.DEFAULT_CORS_HEADERS[key]))
+
+                if (key === 'Access-Control-Allow-Origin') {
+                    if (this.currentEvent.cors?.origins || this.currentEvent.cors?.origin) {
+                        obj.schema.example = this.currentEvent.cors?.origins?.toString() || this.currentEvent.cors?.origin?.toString()
+                    } else if (this.currentEvent.cors?.allowedOrigins) {
+                        obj.schema.example = this.currentEvent.cors.allowedOrigins.toString()
+                    }
+                }
+
+                Object.assign(newHeaders, {[key]: obj})
+            }
+
+            headers = await this.createResponseHeaders(newHeaders)
+                .catch(err => {
+                    throw err;
+                })
+        }
+
+        return headers;
+    }
+
     async createResponseHeaders(headers) {
         const obj = {}
+
         for (const header of Object.keys(headers)) {
             const newHeader = {}
             newHeader.description = headers[header].description || ''

package/src/openAPIGenerator.js

@@ -12,7 +12,19 @@ class OpenAPIGenerator {
         this.logOutput = log;
         this.serverless = serverless
         this.options = options
-        this.defaultLog = 'notice';
+
+        this.logTypes = {
+          NOTICE: 'notice',
+          DEBUG: 'debug',
+          ERROR: 'error',
+          WARNING: 'warning',
+          INFO: 'info',
+          VERBOSE: 'verbose',
+          SUCCESS: 'success',
+        }
+
+        this.defaultLog = this.logTypes.NOTICE;
+
         this.commands = {
           openapi: {
             commands: {
@@ -81,7 +93,7 @@ class OpenAPIGenerator {
         })
     }
 
-    log(type = this.defaultLog, str) {
+    log(str, type = this.defaultLog) {
         switch(this.serverless.version[0]) {
           case '2':
             let colouredString = str
@@ -105,7 +117,7 @@ class OpenAPIGenerator {
     }
 
     async generate() {
-        this.log(this.defaultLog, chalk.bold.underline('OpenAPI v3 Document Generation'))
+        this.log(chalk.bold.underline('OpenAPI v3 Document Generation'))
         this.processCliInput()
 
         const validOpenAPI = await this.generationAndValidation()
@@ -129,9 +141,9 @@ class OpenAPIGenerator {
         }
         try {
           fs.writeFileSync(this.config.file, output);
-          this.log('success', 'OpenAPI v3 Documentation Successfully Written')
+          this.log('OpenAPI v3 Documentation Successfully Written', this.logTypes.SUCCESS)
         } catch (err) {
-          this.log('error', `ERROR: An error was thrown whilst writing the openAPI Documentation`)
+          this.log(`ERROR: An error was thrown whilst writing the openAPI Documentation`, this.logTypes.ERROR)
           throw new this.serverless.classes.Error(err)
         }
     }
@@ -141,19 +153,19 @@ class OpenAPIGenerator {
 
       await generator.parse()
         .catch(err => {
-          this.log('error', `ERROR: An error was thrown generating the OpenAPI v3 documentation`)
+          this.log(`ERROR: An error was thrown generating the OpenAPI v3 documentation`, this.logTypes.ERROR)
           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.log(`ERROR: An error was thrown validating the OpenAPI v3 documentation`, this.logTypes.ERROR)
           this.validationErrorDetails(err)
           throw new this.serverless.classes.Error(err)
         })
 
 
-      this.log('success', 'OpenAPI v3 Documentation Successfully Generated')
+      this.log('OpenAPI v3 Documentation Successfully Generated', this.logTypes.SUCCESS)
 
       return generator.openAPI
     }
@@ -161,16 +173,16 @@ class OpenAPIGenerator {
     createPostman(openAPI) {
       const postmanGeneration = (err, result) => {
         if (err) {
-          this.log('error', `ERROR: An error was thrown when generating the postman collection`)
+          this.log(`ERROR: An error was thrown when generating the postman collection`, this.logTypes.ERROR)
           throw new this.serverless.classes.Error(err)
         }
 
-        this.log('success', 'postman collection v2 Documentation Successfully Generated')
+        this.log('postman collection v2 Documentation Successfully Generated', this.logTypes.SUCCESS)
         try {
           fs.writeFileSync(this.config.postmanCollection, JSON.stringify(result.output[0].data))
-          this.log('success', 'postman collection v2 Documentation Successfully Written')
+          this.log('postman collection v2 Documentation Successfully Written', this.logTypes.SUCCESS)
         } catch (err) {
-          this.log('error', `ERROR: An error was thrown whilst writing the postman collection`)
+          this.log(`ERROR: An error was thrown whilst writing the postman collection`, this.logTypes.ERROR)
           throw new this.serverless.classes.Error(err)
         }
       }
@@ -204,7 +216,6 @@ class OpenAPIGenerator {
         ((config.format === 'yaml') ? 'openapi.yml' : 'openapi.json');
 
       this.log(
-        this.defaultLog,
         `${chalk.bold.green('[OPTIONS]')}
   openApiVersion: "${chalk.bold.green(String(config.openApiVersion))}"
   format: "${chalk.bold.green(config.format)}"
@@ -217,9 +228,9 @@ class OpenAPIGenerator {
     }
 
     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`);
+      this.log(`${chalk.bold.yellow('[VALIDATION]')} Failed to validate OpenAPI document: \n`, this.logTypes.ERROR);
+      this.log(`${chalk.bold.yellow('Context:')} ${JSON.stringify(validationError.options.context[validationError.options.context.length-1], null, 2)}\n`, this.logTypes.ERROR);
+      this.log(`${chalk.bold.yellow('Error Message:')} ${JSON.stringify(validationError.message, null, 2)}\n`, this.logTypes.ERROR);
     }
 }