serverless-openapi-documenter 0.0.53 → 0.0.61

package/README.md

@@ -389,6 +389,23 @@ custom:
 
 `&ErrorItem` in the above example creates a node anchor (&ErrorItem) to the `ErrorResponse` schema which then can be used in the `PutDocumentResponse` schema via the reference (*ErrorItem).  The node anchor needs to be declared first before it can be used elsewhere via the reference, swapping the above example around would result in an error.
 
+##### ModelsList - Backwards compatibility
+
+It was brought to my attention that an older plugin version allowed the use of `modelsList`.  As of 0.0.60, you can continue to use `modelsList` as well as using `models`, however `modelsList` now has to be nested within the `documentation` section.  You can write `modelsList` the same way as any of the two styles for [Models](#Models).
+
+```
+custom:
+  documentation:
+    ...
+    modelsList:
+      - name: "ErrorResponse"
+        description: "This is an error"
+        content:
+          application/json:
+            schema:
+              type: string
+```
+
 
 #### Functions
 
@@ -605,6 +622,46 @@ functions:
               - {}
 ```
 
+##### private
+
+If you use the [private](https://www.serverless.com/framework/docs/providers/aws/events/apigateway#setting-api-keys-for-your-rest-api) property on your event:
+
+```yml
+functions:
+  getData:
+    events:
+      - http:
+          path: /
+          method: get
+          private: true
+```
+
+It will automatically setup an apiKey security scheme of `x-api-key` attached to that method.  You don't need to add this to the [Security Scheme](#securityschemes) in the main documentation.  If you have already added a Security Scheme of an `apiKey` with a name of `x-api-key`, it will associate with that key.
+
+```yml
+custom:
+  documentation:
+    securitySchemes:
+      my_api_key:
+        type: apiKey
+        name: x-api-key
+        in: header
+    security:
+      - my_api_key: []
+
+functions:
+  getData:
+    events:
+      - http:
+          path: /
+          method: get
+          private: true
+          documentation:
+            ...
+```
+
+Will set the Security Scheme to `my_api_key` for that operation.
+
 #### `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).

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "serverless-openapi-documenter",
-  "version": "0.0.53",
+  "version": "0.0.61",
   "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)
 
@@ -303,6 +312,29 @@ class DefinitionGenerator {
             obj.security = documentation.security
         }
 
+        if (this.currentEvent?.private && this.currentEvent.private === true) {
+            let apiKeyName = 'x-api-key'
+            let hasXAPIKey = false
+            if (this.openAPI?.components?.[this.componentTypes.securitySchemes]) {
+                for (const [schemeName, schemeValue] of Object.entries(this.openAPI.components[this.componentTypes.securitySchemes])) {
+                    if (schemeValue.type === 'apiKey' && schemeValue.name === 'x-api-key') {
+                        apiKeyName = schemeName
+                        hasXAPIKey = true
+                    }
+                }
+            }
+
+            if (hasXAPIKey === false) {
+                this.createSecuritySchemes({[apiKeyName]: {type: 'apiKey', name: apiKeyName, in: 'header'}})
+            }
+
+            if (obj.security) {
+                obj.security.push({[apiKeyName]: []})
+            } else {
+                obj.security = [{[apiKeyName]: []}]
+            }
+        }
+
         if (Object.keys(documentation).includes('deprecated'))
             obj.deprecated = documentation.deprecated
 
@@ -360,7 +392,8 @@ class DefinitionGenerator {
                     }
                 }
             } else {
-                obj.headers = corsHeaders
+                if (Object.keys(corsHeaders).length)
+                    obj.headers = corsHeaders
             }
 
             Object.assign(responses, { [response.statusCode]: obj })
@@ -414,7 +447,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
                     })
@@ -445,7 +478,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,10 +510,11 @@ 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
                 }
@@ -525,7 +559,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 +573,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

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"
+              }
+            }
+          }
+        }
+      }
+    }
+  ]
+}