serverless-openapi-documenter 0.0.50 → 0.0.52

package/README.md

@@ -295,12 +295,22 @@ custom:
         contentType: "application/json"
         schema:
           $schema: "http://json-schema.org/draft-04/schema#"
+          type: object
           properties:
             SomeObject:
               type: "object"
               properties:
                 SomeAttribute:
                   type: "string"
+        examples:
+          - name: someObjectInlineExample
+            summary: an example of a request
+            description: a longer string than the summary
+            value: {SomeObject: {SomeAttribute: 'attribute'}}
+          - name: someObjectExternalExample
+            summary: an example of a request external
+            description: a longer string than the summary
+            externalValue: https://example.com/external.json
 ```
 
 The Second way of writing the models:
@@ -329,12 +339,22 @@ custom:
           application/json:
             schema:
               $schema: "http://json-schema.org/draft-04/schema#"
+              type: object
               properties:
                 SomeObject:
                   type: "object"
                   properties:
                     SomeAttribute:
                       type: "string"
+            examples:
+              - name: someObjectInlineExample
+                summary: an example of a request
+                description: a longer string than the summary
+                value: {SomeObject: {SomeAttribute: 'attribute'}}
+              - name: someObjectExternalExample
+                summary: an example of a request external
+                description: a longer string than the summary
+                externalValue: https://example.com/external.json
 ```
 
 ##### Model re-use
@@ -403,6 +423,7 @@ functions:
       - http:
         path: create
         method: post
+        cors: true
         summary:
         documentation:
           summary: "Create User"
@@ -645,6 +666,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.50",
+  "version": "0.0.52",
   "description": "Generate OpenAPI v3 documentation and Postman Collections from your Serverless Config",
   "main": "index.js",
   "keywords": [

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 || ''
@@ -385,16 +458,22 @@ class DefinitionGenerator {
                 }
                 const obj = {}
 
-                if (mediaTypeDocumentation.example)
-                    obj.example = mediaTypeDocumentation.example
-
-                if (mediaTypeDocumentation.examples)
-                    obj.examples = this.createExamples(mediaTypeDocumentation.examples)
-
                 let schema
                 if (mediaTypeDocumentation?.content) {
+                    if (mediaTypeDocumentation.content[contentKey]?.example)
+                        obj.example = mediaTypeDocumentation.content[contentKey].example
+
+                    if (mediaTypeDocumentation.content[contentKey]?.examples)
+                        obj.examples = this.createExamples(mediaTypeDocumentation.content[contentKey].examples)
+
                     schema = mediaTypeDocumentation.content[contentKey].schema
                 } else if (mediaTypeDocumentation?.contentType && mediaTypeDocumentation.schema) {
+                    if (mediaTypeDocumentation?.example)
+                        obj.example = mediaTypeDocumentation.example
+
+                    if (mediaTypeDocumentation?.examples)
+                        obj.examples = this.createExamples(mediaTypeDocumentation.examples)
+
                     schema = mediaTypeDocumentation.schema
                 }
 
@@ -675,6 +754,7 @@ class DefinitionGenerator {
 
         for(const example of examples) {
             Object.assign(examplesObj, {[example.name]: example})
+            delete examplesObj[example.name].name
         }
 
         return examplesObj;