serverless-openapi-documenter 0.0.52 → 0.0.60

package/package.json

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

package/src/definitionGenerator.js

@@ -4,9 +4,8 @@ const path = require('path')
 
 const { v4: uuid } = require('uuid')
 const validator = require('oas-validator');
-const SchemaConvertor = require('json-schema-for-openapi')
-const $RefParser = require("@apidevtools/json-schema-ref-parser")
-const isEqual = require('lodash.isequal')
+
+const SchemaHandler = require('./schemaHandler')
 
 class DefinitionGenerator {
     constructor(serverless, options = {}) {
@@ -25,8 +24,13 @@ class DefinitionGenerator {
 
         this.openAPI = {
             openapi: this.version,
+            components: {
+                schemas: {}
+            }
         }
 
+        this.schemaHandler = new SchemaHandler(serverless, this.openAPI)
+
         this.operationIds = []
         this.schemaIDs = []
 
@@ -64,6 +68,11 @@ class DefinitionGenerator {
     async parse() {
         this.createInfo()
 
+        await this.schemaHandler.addModelsToOpenAPI()
+            .catch(err => {
+                throw err
+            })
+
         if (this.serverless.service.custom.documentation.securitySchemes) {
             this.createSecuritySchemes(this.serverless.service.custom.documentation.securitySchemes)
 
@@ -79,7 +88,7 @@ class DefinitionGenerator {
 
         if (this.serverless.service.custom.documentation.servers) {
             const servers = this.createServers(this.serverless.service.custom.documentation.servers)
-            Object.assign(this.openAPI, {servers: servers})
+            Object.assign(this.openAPI, { servers: servers })
         }
 
         if (this.serverless.service.custom.documentation.tags) {
@@ -88,7 +97,7 @@ class DefinitionGenerator {
 
         if (this.serverless.service.custom.documentation.externalDocumentation) {
             const extDoc = this.createExternalDocumentation(this.serverless.service.custom.documentation.externalDocumentation)
-            Object.assign(this.openAPI, {externalDocs: extDoc})
+            Object.assign(this.openAPI, { externalDocs: extDoc })
         }
     }
 
@@ -113,7 +122,7 @@ class DefinitionGenerator {
                 contactObj.url = documentation.contact.url
 
             contactObj.email = documentation.contact.email || ''
-            Object.assign(info, {contact: contactObj})
+            Object.assign(info, { contact: contactObj })
         }
 
         if (documentation.license && documentation.license.name) {
@@ -123,16 +132,16 @@ class DefinitionGenerator {
             if (documentation.license.url)
                 licenseObj.url = documentation.license.url || ''
 
-            Object.assign(info, {license: licenseObj})
+            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(info, { [key]: documentation[key] })
             }
         }
 
-        Object.assign(this.openAPI, {info})
+        Object.assign(this.openAPI, { info })
     }
 
     async createPaths() {
@@ -173,18 +182,18 @@ class DefinitionGenerator {
                     let slashPath = (event?.http?.path || event.httpApi?.path) ?? '/'
                     const pathStart = new RegExp(/^\//, 'g')
                     if (pathStart.test(slashPath) === false) {
-                        slashPath = `/${(event?.http?.path||event.httpApi?.path)?? ''}`
+                        slashPath = `/${(event?.http?.path || event.httpApi?.path) ?? ''}`
                     }
 
                     if (paths[slashPath]) {
                         Object.assign(paths[slashPath], path);
                     } else {
-                        Object.assign(paths, {[slashPath]: path});
+                        Object.assign(paths, { [slashPath]: path });
                     }
                 }
             }
         }
-        Object.assign(this.openAPI, {paths})
+        Object.assign(this.openAPI, { paths })
     }
 
     createServers(servers) {
@@ -227,7 +236,7 @@ class DefinitionGenerator {
     }
 
     createExternalDocumentation(docs) {
-        return {...docs}
+        return { ...docs }
         // const documentation = this.serverless.service.custom.documentation
         // if (documentation.externalDocumentation) {
         //     // Object.assign(this.openAPI, {externalDocs: {...documentation.externalDocumentation}})
@@ -251,7 +260,7 @@ class DefinitionGenerator {
             }
             tags.push(obj)
         }
-        Object.assign(this.openAPI, {tags: tags})
+        Object.assign(this.openAPI, { tags: tags })
     }
 
     async createOperationObject(method, documentation, name = uuid()) {
@@ -323,7 +332,7 @@ class DefinitionGenerator {
             obj.servers = servers
         }
 
-        return {[method.toLowerCase()]: obj}
+        return { [method.toLowerCase()]: obj }
     }
 
     async createResponses(documentation) {
@@ -360,10 +369,11 @@ class DefinitionGenerator {
                     }
                 }
             } else {
-                obj.headers = corsHeaders
+                if (Object.keys(corsHeaders).length)
+                    obj.headers = corsHeaders
             }
 
-            Object.assign(responses,{[response.statusCode]: obj})
+            Object.assign(responses, { [response.statusCode]: obj })
         }
 
         return responses
@@ -380,7 +390,7 @@ class DefinitionGenerator {
             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) {
+                    (this.currentEvent.cors.allowCredentials === undefined || this.currentEvent.cors?.allowCredentials === false)) {
                     continue
                 }
 
@@ -394,7 +404,7 @@ class DefinitionGenerator {
                     }
                 }
 
-                Object.assign(newHeaders, {[key]: obj})
+                Object.assign(newHeaders, { [key]: obj })
             }
 
             headers = await this.createResponseHeaders(newHeaders)
@@ -414,7 +424,7 @@ class DefinitionGenerator {
             newHeader.description = headers[header].description || ''
 
             if (headers[header].schema) {
-                const schemaRef = await this.schemaCreator(headers[header].schema, header)
+                const schemaRef = await this.schemaHandler.createSchema(header, headers[header].schema)
                     .catch(err => {
                         throw err
                     })
@@ -423,7 +433,7 @@ class DefinitionGenerator {
                 }
             }
 
-            Object.assign(obj, {[header]: newHeader})
+            Object.assign(obj, { [header]: newHeader })
         }
 
         return obj
@@ -445,7 +455,7 @@ class DefinitionGenerator {
 
     async createMediaTypeObject(models, type) {
         const mediaTypeObj = {}
-        for (const mediaTypeDocumentation of this.serverless.service.custom.documentation.models) {
+        for (const mediaTypeDocumentation of this.schemaHandler.models) {
             if (models === undefined || models === null) {
                 throw new Error(`${this.currentFunctionName} is missing a Response Model for statusCode ${this.currentStatusCode}`)
             }
@@ -477,15 +487,16 @@ class DefinitionGenerator {
                     schema = mediaTypeDocumentation.schema
                 }
 
-                const schemaRef = await this.schemaCreator(schema, mediaTypeDocumentation.name)
+                const schemaRef = await this.schemaHandler.createSchema(mediaTypeDocumentation.name)
                     .catch(err => {
                         throw err
                     })
+
                 obj.schema = {
                     $ref: schemaRef
                 }
 
-                Object.assign(mediaTypeObj, {[contentKey]: obj})
+                Object.assign(mediaTypeObj, { [contentKey]: obj })
             }
         }
         return mediaTypeObj
@@ -525,7 +536,7 @@ class DefinitionGenerator {
                 obj.examples = this.createExamples(param.examples)
 
             if (param.schema) {
-                const schemaRef = await this.schemaCreator(param.schema, param.name)
+                const schemaRef = await this.schemaHandler.createSchema(param.name, param.schema)
                     .catch(err => {
                         throw err
                     })
@@ -539,76 +550,6 @@ class DefinitionGenerator {
         return params;
     }
 
-    async dereferenceSchema(schema) {
-        let originalSchema = await $RefParser.bundle(schema, this.refParserOptions)
-            .catch(err => {
-                console.error(err)
-                throw err
-            })
-
-        let deReferencedSchema = await $RefParser.dereference(originalSchema, this.refParserOptions)
-            .catch(err => {
-                console.error(err)
-                throw err
-            })
-
-        // deal with schemas that have been de-referenced poorly: naive
-        if (deReferencedSchema?.$ref === '#') {
-            const oldRef = originalSchema.$ref
-            const path = oldRef.split('/')
-
-            const pathTitle = path[path.length-1]
-            const referencedProperties = deReferencedSchema.definitions[pathTitle]
-
-            Object.assign(deReferencedSchema, {...referencedProperties})
-
-            delete deReferencedSchema.$ref
-            deReferencedSchema = await this.dereferenceSchema(deReferencedSchema)
-                .catch((err) => {
-                    throw err
-                })
-        }
-
-        return deReferencedSchema
-    }
-
-    async schemaCreator(schema, name) {
-        let schemaName = name
-        let finalName = schemaName
-        const dereferencedSchema = await this.dereferenceSchema(schema)
-            .catch(err => {
-                console.error(err)
-                throw err
-            })
-
-        const convertedSchemas = SchemaConvertor.convert(dereferencedSchema, schemaName)
-
-        for (const convertedSchemaName of Object.keys(convertedSchemas.schemas)) {
-            const convertedSchema = convertedSchemas.schemas[convertedSchemaName]
-            if (this.existsInComponents(convertedSchemaName)) {
-                if (this.isTheSameSchema(convertedSchema, convertedSchemaName) === false) {
-                    if (convertedSchemaName === schemaName) {
-                        finalName = `${schemaName}-${uuid()}`
-                        this.addToComponents(this.componentTypes.schemas, convertedSchema, finalName)
-                    } else
-                        this.addToComponents(this.componentTypes.schemas, convertedSchema, convertedSchemaName)
-                }
-            } else {
-                this.addToComponents(this.componentTypes.schemas, convertedSchema, convertedSchemaName)
-            }
-        }
-
-        return `#/components/schemas/${finalName}`
-    }
-
-    existsInComponents(name) {
-        return Boolean(this.openAPI?.components?.schemas?.[name])
-    }
-
-    isTheSameSchema(schema, otherSchemaName) {
-        return isEqual(schema, this.openAPI.components.schemas[otherSchemaName])
-    }
-
     addToComponents(type, schema, name) {
         const schemaObj = {
             [name]: schema
@@ -618,7 +559,7 @@ class DefinitionGenerator {
             if (this.openAPI.components[type]) {
                 Object.assign(this.openAPI.components[type], schemaObj)
             } else {
-                Object.assign(this.openAPI.components, {[type]: schemaObj})
+                Object.assign(this.openAPI.components, { [type]: schemaObj })
             }
         } else {
             const components = {
@@ -639,30 +580,30 @@ class DefinitionGenerator {
             if (securityScheme.description)
                 schema.description = securityScheme.description
 
-            switch(securityScheme.type.toLowerCase()) {
+            switch (securityScheme.type.toLowerCase()) {
                 case 'apikey':
                     const apiKeyScheme = this.createAPIKeyScheme(securityScheme)
                     schema.type = 'apiKey'
                     Object.assign(schema, apiKeyScheme)
-                break;
+                    break;
 
                 case 'http':
                     const HTTPScheme = this.createHTTPScheme(securityScheme)
                     schema.type = 'http'
                     Object.assign(schema, HTTPScheme)
-                break;
+                    break;
 
                 case 'openidconnect':
                     const openIdConnectScheme = this.createOpenIDConnectScheme(securityScheme)
                     schema.type = 'openIdConnect'
                     Object.assign(schema, openIdConnectScheme)
-                break;
+                    break;
 
                 case 'oauth2':
                     const oAuth2Scheme = this.createOAuth2Scheme(securityScheme)
                     schema.type = 'oauth2'
                     Object.assign(schema, oAuth2Scheme)
-                break;
+                    break;
             }
 
             this.addToComponents(this.componentTypes.securitySchemes, schema, scheme)
@@ -712,7 +653,7 @@ class DefinitionGenerator {
         const schema = {}
         if (securitySchema.flows) {
             const flows = this.createOAuthFlows(securitySchema.flows)
-            Object.assign(schema, {flows: flows})
+            Object.assign(schema, { flows: flows })
         } else
             throw new Error('Security Scheme for "oauth2" requires flows')
 
@@ -744,7 +685,7 @@ class DefinitionGenerator {
             else
                 throw new Error(`oAuth2 ${flow} flow requires scopes`)
 
-            Object.assign(obj, {[flow]: schema})
+            Object.assign(obj, { [flow]: schema })
         }
         return obj
     }
@@ -752,8 +693,8 @@ class DefinitionGenerator {
     createExamples(examples) {
         const examplesObj = {}
 
-        for(const example of examples) {
-            Object.assign(examplesObj, {[example.name]: example})
+        for (const example of examples) {
+            Object.assign(examplesObj, { [example.name]: example })
             delete examplesObj[example.name].name
         }
 

package/src/schemaHandler.js

@@ -0,0 +1,189 @@
+'use strict'
+
+const path = require('path')
+
+const $RefParser = require("@apidevtools/json-schema-ref-parser")
+const SchemaConvertor = require('json-schema-for-openapi')
+const isEqual = require('lodash.isequal')
+const { v4: uuid } = require('uuid')
+
+class SchemaHandler {
+    constructor(serverless, openAPI) {
+        this.documentation = serverless.service.custom.documentation
+        this.openAPI = openAPI
+
+        this.modelReferences = {}
+
+        this.__standardiseModels()
+
+        try {
+            this.refParserOptions = require(path.resolve('options', 'ref-parser.js'))
+        } catch (err) {
+            this.refParserOptions = {}
+        }
+    }
+
+    /**
+     * Standardises the models to a specific format
+     */
+    __standardiseModels() {
+        const standardModel = (model) => {
+            if (model.schema) {
+                return model
+            }
+
+            const contentType = Object.keys(model.content)[0]
+            model.contentType = contentType
+            model.schema = model.content[contentType].schema
+
+            return model
+        }
+
+        const standardisedModels = this.documentation?.models?.map(standardModel) || []
+        const standardisedModelsList = this.documentation?.modelsList?.map(standardModel) || []
+
+        this.models = standardisedModels.length ? standardisedModels.concat(standardisedModelsList) : standardisedModelsList
+    }
+
+    async addModelsToOpenAPI() {
+        for (const model of this.models) {
+            const modelName = model.name
+            const modelSchema = model.schema
+
+            const dereferencedSchema = await this.__dereferenceSchema(modelSchema)
+                .catch(err => {
+                    if(err.errors) {
+                        for (const error of err?.errors) {
+                            if (error.message.includes('HTTP ERROR')) {
+                                throw err
+                            }
+                        }
+                    }
+                    return modelSchema
+                })
+
+            const convertedSchemas = SchemaConvertor.convert(dereferencedSchema, modelName)
+
+            for (const [schemaName, schemaValue] of Object.entries(convertedSchemas.schemas)) {
+                if (schemaName === modelName) {
+                    this.modelReferences[schemaName] = `#/components/schemas/${modelName}`
+                }
+
+                this.__addToComponents('schemas', schemaValue, schemaName)
+            }
+        }
+    }
+
+    async createSchema(name, schema) {
+        let originalName = name;
+        let finalName = name;
+
+        if (this.modelReferences[name] && schema === undefined) {
+            return this.modelReferences[name]
+        }
+
+        const dereferencedSchema = await this.__dereferenceSchema(schema)
+            .catch(err => {
+                throw err
+            })
+
+        const convertedSchemas = SchemaConvertor.convert(dereferencedSchema, name)
+
+        for (const [schemaName, schemaValue] of Object.entries(convertedSchemas.schemas)) {
+            if (this.__existsInComponents(schemaName)) {
+                if (this.__isTheSameSchema(schemaValue, schemaName) === false) {
+                    if (schemaName === originalName) {
+                        finalName = `${schemaName}-${uuid()}`
+                        this.__addToComponents('schemas', schemaValue, finalName)
+                    } else {
+                        this.__addToComponents('schemas', schemaValue, schemaName)
+                    }
+                }
+            } else {
+                this.__addToComponents('schemas', schemaValue, schemaName)
+            }
+        }
+
+        return `#/components/schemas/${finalName}`
+    }
+
+    async __dereferenceSchema(schema) {
+        const bundledSchema = await $RefParser.bundle(schema, this.refParserOptions)
+            .catch(err => {
+                throw err
+            })
+
+        let deReferencedSchema = await $RefParser.dereference(bundledSchema, this.refParserOptions)
+            .catch(err => {
+                throw err
+            })
+
+        // deal with schemas that have been de-referenced poorly: naive
+        if (deReferencedSchema?.$ref === '#') {
+            const oldRef = bundledSchema.$ref
+            const path = oldRef.split('/')
+
+            const pathTitle = path[path.length - 1]
+            const referencedProperties = deReferencedSchema.definitions[pathTitle]
+
+            Object.assign(deReferencedSchema, { ...referencedProperties })
+
+            delete deReferencedSchema.$ref
+            deReferencedSchema = await this.__dereferenceSchema(deReferencedSchema)
+                .catch((err) => {
+                    throw err
+                })
+        }
+
+        return deReferencedSchema
+    }
+
+    /**
+     * @function existsInComponents
+     * @param {string} name - The name of the Schema
+     * @returns {boolean} Whether it exists in components already
+     */
+    __existsInComponents(name) {
+        return Boolean(this.openAPI?.components?.schemas?.[name])
+    }
+
+    /**
+     * @function isTheSameSchema
+     * @param {object} schema - The schema value
+     * @param {string} otherSchemaName - The name of the schema
+     * @returns {boolean} Whether the schema provided is the same one as in components already
+     */
+    __isTheSameSchema(schema, otherSchemaName) {
+        return isEqual(schema, this.openAPI.components.schemas[otherSchemaName])
+    }
+
+    /**
+     * @function addToComponents
+     * @param {string} type - The component type
+     * @param {object} schema - The schema
+     * @param {string} name - The name of the schema
+     */
+    __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)
+        }
+    }
+}
+
+module.exports = SchemaHandler;

package/test/models/models/models-alt.json

@@ -0,0 +1,17 @@
+{
+  "models": [
+    {
+      "name": "ErrorResponse",
+      "description": "The Error Response",
+      "contentType": "application/json",
+      "schema": {
+        "type": "object",
+        "properties": {
+          "error": {
+            "type": "string"
+          }
+        }
+      }
+    }
+  ]
+}

package/test/models/models/models.json

@@ -0,0 +1,20 @@
+{
+  "models": [
+    {
+      "name": "ErrorResponse",
+      "description": "The Error Response",
+      "content": {
+        "application/json": {
+          "schema": {
+            "type": "object",
+            "properties": {
+              "error": {
+                "type": "string"
+              }
+            }
+          }
+        }
+      }
+    }
+  ]
+}

package/test/models/models/modelsList-alt.json

@@ -0,0 +1,17 @@
+{
+    "modelsList": [
+        {
+            "name": "ErrorResponse",
+            "description": "The Error Response",
+            "contentType": "application/json",
+            "schema": {
+                "type": "object",
+                "properties": {
+                    "error": {
+                        "type": "string"
+                    }
+                }
+            }
+        }
+    ]
+}

package/test/models/models/modelsList.json

@@ -0,0 +1,20 @@
+{
+  "modelsList": [
+    {
+      "name": "ErrorResponse",
+      "description": "The Error Response",
+      "content": {
+        "application/json": {
+          "schema": {
+            "type": "object",
+            "properties": {
+              "error": {
+                "type": "string"
+              }
+            }
+          }
+        }
+      }
+    }
+  ]
+}