serverless-openapi-documenter 0.0.33 → 0.0.40

package/README.md

@@ -52,6 +52,16 @@ Options:
 --postmanCollection     -p  Will generate a postman collection (from the generated openAPI documentation), in json only, if passed in. Default postman.json
 ```
 
+### README Highlighted Reading
+
+#### Security Details
+* [Security](#securityschemes)
+* [Security on All Operations](#security-on-each-operation)
+* [Security Per Operation](#security)
+#### Model Details
+* [Models](#models)
+* [Notes on Schemas](#notes-on-schemas)
+
 ### OpenAPI Mapping
 
 | OpenAPI field            | Serverless field                                                                   |
@@ -184,6 +194,7 @@ custom:
 ```
 
 Name is required but `url` is optional and must be in the format of a url.
+
 #### Extended Fields
 
 You can also add extended fields to the documentation object:

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "serverless-openapi-documenter",
-  "version": "0.0.33",
+  "version": "0.0.40",
   "description": "Generate OpenAPI v3 documentation and Postman Collections from your Serverless Config",
   "main": "index.js",
   "keywords": [
@@ -32,6 +32,7 @@
     "chalk": "^4.1.2",
     "js-yaml": "^4.1.0",
     "json-schema-for-openapi": "^0.3.1",
+    "lodash.isequal": "^4.5.0",
     "oas-validator": "^5.0.8",
     "openapi-to-postmanv2": "^4.4.1",
     "swagger2openapi": "^7.0.8",

package/src/definitionGenerator.js

@@ -5,7 +5,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 $RefParser = require("@apidevtools/json-schema-ref-parser")
+const isEqual = require('lodash.isequal')
 
 class DefinitionGenerator {
     constructor(serverless, options = {}) {
@@ -29,6 +30,11 @@ class DefinitionGenerator {
         this.operationIds = []
         this.schemaIDs = []
 
+        this.componentTypes = {
+            schemas: 'schemas',
+            securitySchemes: 'securitySchemes'
+        }
+
         try {
             this.refParserOptions = require(path.resolve('options', 'ref-parser.js'))
         } catch (err) {
@@ -455,42 +461,13 @@ class DefinitionGenerator {
     }
 
     async dereferenceSchema(schema) {
-        return await $RefParser.dereference(schema, this.refParserOptions)
+        let deReferencedSchema = await $RefParser.dereference(schema, this.refParserOptions)
             .catch(err => {
                 console.error(err)
                 throw err
             })
-    }
-
-    async schemaCreator(schema, name) {
-        const addToComponents = (schema, name) => {
-            const schemaObj = {
-                [name]: schema
-            }
-
-            if (this.openAPI?.components) {
-                if (this.openAPI.components?.schemas) {
-                    Object.assign(this.openAPI.components.schemas, schemaObj)
-                } else {
-                    Object.assign(this.openAPI.components, {schemas: schemaObj})
-                }
-            } else {
-                const components = {
-                    components: {
-                        schemas: schemaObj
-                    }
-                }
-
-                Object.assign(this.openAPI, components)
-            }
-        }
-
-        let deReferencedSchema = await this.dereferenceSchema(schema)
-            .catch((err) => {
-                throw err
-            })
 
-        // deal with schemas that have been de-referenced poorly
+        // deal with schemas that have been de-referenced poorly: naive
         if (deReferencedSchema.$ref === '#') {
             const oldRef = schema.$ref
             const path = oldRef.split('/')
@@ -505,35 +482,44 @@ class DefinitionGenerator {
                 })
         }
 
-        const convertedSchema = SchemaConvertor.convert(deReferencedSchema, name)
-        let schemaName = name
-        if (this.schemaIDs.includes(schemaName))
-            schemaName = `${name}-${uuid()}`
-
-        this.schemaIDs.push(schemaName)
+        return deReferencedSchema
+    }
 
-        for (const key of Object.keys(convertedSchema.schemas)) {
-            if (key === name || key.split('-')[0] === name) {
-                let ref = `#/components/schemas/`
+    async schemaCreator(schema, name) {
+        let schemaName = name
+        let finalName = schemaName
+        const dereferencedSchema = await this.dereferenceSchema(schema)
+            .catch(err => {
+                console.error(err)
+                throw err
+            })
 
-                if (this.openAPI?.components?.schemas?.[name]) {
-                    if (JSON.stringify(convertedSchema.schemas[key]) === JSON.stringify(this.openAPI.components.schemas[name])) {
-                        return `${ref}${name}`
-                    }
+        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)
                 }
-
-                addToComponents(convertedSchema.schemas[key], schemaName)
-                return `${ref}${schemaName}`
             } else {
-                if (this.openAPI?.components?.schemas?.[key]) {
-                    if (JSON.stringify(convertedSchema.schemas[key]) !== JSON.stringify(this.openAPI.components.schemas[key])) {
-                        addToComponents(convertedSchema.schemas[key], key)
-                    }
-                } else {
-                    addToComponents(convertedSchema.schemas[key], key)
-                }
+                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) {
@@ -592,7 +578,7 @@ class DefinitionGenerator {
                 break;
             }
 
-            this.addToComponents('securitySchemes', schema, scheme)
+            this.addToComponents(this.componentTypes.securitySchemes, schema, scheme)
         }
     }
 

package/test/unit/definitionGenerator.spec.js

@@ -709,234 +709,165 @@ describe('DefinitionGenerator', () => {
                 expect(expected).to.equal('#/components/schemas/main')
             });
 
-            it('should add each definition of a complex schema to the components object', async function() {
-                const complexSchema = {
-                    "$schema": "http://json-schema.org/draft-04/schema#",
-                    "title": "JSON API Schema",
-                    "description": "This is a blah blah for responses in the JSON API format. For more, see http://jsonapi.org",
-                    "type": "object",
-                    "required": [
-                        "errors"
-                    ],
-                    "properties": {
-                        "errors": {
-                            "type": "array",
-                            "items": {
-                                "$ref": "#/definitions/error"
-                            },
-                            "uniqueItems": true
-                        }
-                    },
-                    "definitions": {
-                        "error": {
-                            "type": "object",
-                            "properties": {
-                                "id": {
-                                    "description": "A unique identifier for this particular occurrence of the problem.",
-                                    "type": "string"
-                                }
-                            }
-                        }
-                    }
-                }
+            it('should not overwrite a schema that has the same name and same schema as a pre-existing schema', async function() {
                 const definitionGenerator = new DefinitionGenerator(mockServerless)
-                const expected = await definitionGenerator.schemaCreator(complexSchema, 'PutRequest')
-                    .catch((err) => {
-                        console.error(err)
-                    })
 
-                expect(definitionGenerator.openAPI.components.schemas).to.have.property('PutRequest')
-                expect(definitionGenerator.openAPI.components.schemas).to.not.have.property('error')
-                expect(expected).to.equal('#/components/schemas/PutRequest')
-            });
+                const spy = sinon.spy(definitionGenerator, 'addToComponents')
 
-            it(`should not overwrite an object that already exists in the components if they're the same`, async function() {
                 const complexSchema = {
-                    "$schema": "http://json-schema.org/draft-04/schema#",
-                    "title": "JSON API Schema",
-                    "description": "This is a blah blah for responses in the JSON API format. For more, see http://jsonapi.org",
-                    "type": "object",
-                    "required": [
-                        "errors"
-                    ],
-                    "properties": {
-                        "errors": {
-                            "type": "array",
-                            "items": {
-                                "$ref": "#/definitions/error"
-                            },
-                            "uniqueItems": true
-                        }
-                    },
-                    "definitions": {
-                        "error": {
-                            "type": "object",
-                            "properties": {
-                                "id": {
-                                    "description": "A unique identifier for this particular occurrence of the problem.",
-                                    "type": "string"
-                                }
-                            }
+                    type: 'object',
+                    properties: {
+                        error: {
+                            type: 'string'
                         }
                     }
                 }
-                const definitionGenerator = new DefinitionGenerator(mockServerless)
-                let expected = await definitionGenerator.schemaCreator(complexSchema, 'PutRequest')
+
+                let expected = await definitionGenerator.schemaCreator(complexSchema, 'main')
                     .catch((err) => {
                         console.error(err)
                     })
 
-                expect(definitionGenerator.openAPI.components.schemas).to.have.property('PutRequest')
-                expect(definitionGenerator.openAPI.components.schemas).to.not.have.property('error')
-                expect(expected).to.equal('#/components/schemas/PutRequest')
+                expect(definitionGenerator.openAPI.components.schemas).to.have.property('main')
+                expect(JSON.stringify(definitionGenerator.openAPI.components.schemas.main)).to.equal(JSON.stringify(complexSchema))
+                expect(expected).to.equal('#/components/schemas/main')
 
-                expected = await definitionGenerator.schemaCreator(complexSchema, 'PutRequest')
-                    .catch((err) => {
+                expected = await definitionGenerator.schemaCreator(complexSchema, 'main')
+                     .catch((err) => {
                         console.error(err)
                     })
 
-                expect(definitionGenerator.openAPI.components.schemas).to.have.property('PutRequest')
-                expect(definitionGenerator.openAPI.components.schemas).to.not.have.property('error')
-                expect(expected).to.equal('#/components/schemas/PutRequest')
+                expect(expected).to.equal('#/components/schemas/main')
+                expect(spy.callCount).to.be.equal(1)
+
+                spy.resetHistory()
             });
 
-            it(`should create a new object for a similarly named object but with different properties`, async function() {
+            it('should not overwrite a schema that has the same name and same schema as a pre-existing schema but in a slightly different order', async function() {
+                const definitionGenerator = new DefinitionGenerator(mockServerless)
+
+                const spy = sinon.spy(definitionGenerator, 'addToComponents')
+
                 const complexSchema = {
-                    "$schema": "http://json-schema.org/draft-04/schema#",
-                    "title": "JSON API Schema",
-                    "description": "This is a blah blah for responses in the JSON API format. For more, see http://jsonapi.org",
-                    "type": "object",
-                    "required": [
-                        "errors"
-                    ],
-                    "properties": {
-                        "errors": {
-                            "type": "array",
-                            "items": {
-                                "$ref": "#/definitions/error"
-                            },
-                            "uniqueItems": true
-                        }
-                    },
-                    "definitions": {
-                        "error": {
-                            "type": "object",
-                            "properties": {
-                                "id": {
-                                    "description": "A unique identifier for this particular occurrence of the problem.",
-                                    "type": "string"
-                                }
-                            }
+                    type: 'object',
+                    properties: {
+                        error: {
+                            type: 'string',
+                            format: 'uuid'
                         }
                     }
                 }
-                const definitionGenerator = new DefinitionGenerator(mockServerless)
-                let expected = await definitionGenerator.schemaCreator(complexSchema, 'PutRequest')
+
+                let expected = await definitionGenerator.schemaCreator(complexSchema, 'main')
                     .catch((err) => {
                         console.error(err)
                     })
 
-                expect(definitionGenerator.openAPI.components.schemas).to.have.property('PutRequest')
-                expect(definitionGenerator.openAPI.components.schemas).to.not.have.property('error')
-                expect(expected).to.equal('#/components/schemas/PutRequest')
+                expect(definitionGenerator.openAPI.components.schemas).to.have.property('main')
+                expect(JSON.stringify(definitionGenerator.openAPI.components.schemas.main)).to.equal(JSON.stringify(complexSchema))
+                expect(expected).to.equal('#/components/schemas/main')
 
-                complexSchema.properties.cheese = {
-                    type: 'string'
+                const complexSchema2 = {
+                    type: 'object',
+                    properties: {
+                        error: {
+                            format: 'uuid',
+                            type: 'string'
+                        }
+                    }
                 }
 
-                expected = await definitionGenerator.schemaCreator(complexSchema, 'PutRequest')
-                    .catch((err) => {
+                expected = await definitionGenerator.schemaCreator(complexSchema2, 'main')
+                     .catch((err) => {
                         console.error(err)
                     })
 
-                expect(definitionGenerator.openAPI.components.schemas).to.have.property('PutRequest')
-                expect(definitionGenerator.openAPI.components.schemas).to.not.have.property('error')
+                expect(expected).to.equal('#/components/schemas/main')
+                expect(spy.callCount).to.be.equal(1)
 
-                let newSchemaStr = expected.split('/')
-                expect(v4.test(newSchemaStr[newSchemaStr.length-1].split('PutRequest-')[1])).to.be.true
-                expect(definitionGenerator.openAPI.components.schemas).to.have.property(newSchemaStr[newSchemaStr.length-1])
+                spy.resetHistory()
+            });
 
-                // expected = await definitionGenerator.schemaCreator(complexSchema, 'PutRequest')
-                //     .catch((err) => {
-                //         console.error(err)
-                //     })
+            it('should add a schema to components when a name already exists but the schema is different', async function() {
+                const definitionGenerator = new DefinitionGenerator(mockServerless)
 
-                // expect(definitionGenerator.openAPI.components.schemas).to.have.property('PutRequest')
-                // expect(definitionGenerator.openAPI.components.schemas).to.have.property('error')
-                // console.log(expected)
-                // expect(expected)
-                // expect(expected).to.equal('#/components/schemas/PutRequest1')
+                const spy = sinon.spy(definitionGenerator, 'addToComponents')
 
-                complexSchema.properties.wine = {
-                    type: 'string'
+                const complexSchema = {
+                    type: 'object',
+                    properties: {
+                        error: {
+                            type: 'string'
+                        }
+                    }
                 }
 
-                expected = await definitionGenerator.schemaCreator(complexSchema, 'PutRequest')
+                let expected = await definitionGenerator.schemaCreator(complexSchema, 'main')
                     .catch((err) => {
                         console.error(err)
                     })
 
-                expect(definitionGenerator.openAPI.components.schemas).to.have.property('PutRequest')
-                expect(definitionGenerator.openAPI.components.schemas).to.not.have.property('error')
-                expect(definitionGenerator.openAPI.components.schemas).to.have.property(newSchemaStr[newSchemaStr.length-1])
-                newSchemaStr = expected.split('/')
-                expect(v4.test(newSchemaStr[newSchemaStr.length-1].split('PutRequest-')[1])).to.be.true
-                expect(definitionGenerator.openAPI.components.schemas).to.have.property(newSchemaStr[newSchemaStr.length-1])
+                expect(definitionGenerator.openAPI.components.schemas).to.have.property('main')
+                expect(JSON.stringify(definitionGenerator.openAPI.components.schemas.main)).to.equal(JSON.stringify(complexSchema))
+                expect(expected).to.equal('#/components/schemas/main')
+
+                const complexSchema2 = JSON.parse(JSON.stringify(complexSchema))
+                complexSchema2.properties.error.format = 'uuid'
+
+                expected = await definitionGenerator.schemaCreator(complexSchema2, 'main')
+                     .catch((err) => {
+                        console.error(err)
+                    })
+
+                const splitPath = expected.split('/')
+                expect(v4.test(splitPath[3].split('main-')[1])).to.be.true
+                expect(definitionGenerator.openAPI.components.schemas[splitPath[3]]).to.be.an('object')
+                expect(definitionGenerator.openAPI.components.schemas[splitPath[3]].properties.error).to.have.property('format')
+                expect(spy.callCount).to.be.equal(2)
+
+                spy.resetHistory()
             });
 
-            it(`should create a new object for a differently named object but with same properties`, async function() {
+            it('should correctly dereference a schema with definitions and add to the components', async function() {
+                const definitionGenerator = new DefinitionGenerator(mockServerless)
+
                 const complexSchema = {
-                    "$schema": "http://json-schema.org/draft-04/schema#",
-                    "title": "JSON API Schema",
-                    "description": "This is a blah blah for responses in the JSON API format. For more, see http://jsonapi.org",
-                    "type": "object",
-                    "required": [
-                        "errors"
-                    ],
-                    "properties": {
-                        "errors": {
-                            "type": "array",
-                            "items": {
-                                "$ref": "#/definitions/error"
-                            },
-                            "uniqueItems": true
+                    type: 'object',
+                    properties: {
+                        error: {
+                            '$ref': '#/definitions/error'
                         }
                     },
-                    "definitions": {
-                        "error": {
-                            "type": "object",
-                            "properties": {
-                                "id": {
-                                    "description": "A unique identifier for this particular occurrence of the problem.",
-                                    "type": "string"
-                                }
-                            }
+                    definitions: {
+                        error: {
+                            type: "string"
                         }
                     }
                 }
-                const definitionGenerator = new DefinitionGenerator(mockServerless)
-                let expected = await definitionGenerator.schemaCreator(complexSchema, 'PutRequest')
-                    .catch((err) => {
-                        console.error(err)
-                    })
 
-                expect(definitionGenerator.openAPI.components.schemas).to.have.property('PutRequest')
-                expect(definitionGenerator.openAPI.components.schemas).to.not.have.property('error')
-                expect(expected).to.equal('#/components/schemas/PutRequest')
+                const spy = sinon.spy(definitionGenerator, 'dereferenceSchema')
 
-                expected = await definitionGenerator.schemaCreator(complexSchema, 'ContactPutRequest')
+                const expected = await definitionGenerator.schemaCreator(complexSchema, 'main')
                     .catch((err) => {
                         console.error(err)
                     })
 
-                expect(definitionGenerator.openAPI.components.schemas).to.have.property('PutRequest')
-                expect(definitionGenerator.openAPI.components.schemas).to.not.have.property('error')
-                expect(definitionGenerator.openAPI.components.schemas).to.have.property('ContactPutRequest')
-                expect(expected).to.equal('#/components/schemas/ContactPutRequest')
+                expect(definitionGenerator.openAPI.components.schemas).to.have.property('main')
+                expect(definitionGenerator.openAPI.components.schemas.main.properties).to.have.property('error')
+                expect(definitionGenerator.openAPI.components.schemas.main.properties.error).to.have.property('type')
+                expect(definitionGenerator.openAPI.components.schemas.main.properties.error.type).to.be.equal('string')
+                expect(definitionGenerator.openAPI.components.schemas.main).to.not.have.property('definitions')
+                expect(expected).to.equal('#/components/schemas/main')
+
+                expect(spy.callCount).to.be.equal(1)
+
+                spy.resetHistory()
             });
 
-            it('should handle a schema that has been improperly dereferenced', async function() {
-                const simpleSchema = {
+            it('should handle a schema that has been incorrectly dereferenced', async function() {
+                const definitionGenerator = new DefinitionGenerator(mockServerless)
+
+                const complexSchema = {
                     $schema: 'http://json-schema.org/draft-04/schema#',
                     title: 'JSON API Schema',
                     $ref: '#/definitions/Error',
@@ -946,22 +877,72 @@ describe('DefinitionGenerator', () => {
                         }
                     }
                 }
-                const definitionGenerator = new DefinitionGenerator(mockServerless)
-                const expected = await definitionGenerator.schemaCreator(simpleSchema, 'simpleSchema')
+
+                const spy = sinon.spy(definitionGenerator, 'dereferenceSchema')
+
+                const expected = await definitionGenerator.schemaCreator(complexSchema, 'main')
                     .catch((err) => {
                         console.error(err)
                     })
 
-                expect(definitionGenerator.openAPI.components.schemas).to.have.property('simpleSchema')
-                expect(definitionGenerator.openAPI.components.schemas.simpleSchema).to.deep.equal({
-                    title: 'JSON API Schema',
-                    properties: {
-                        Error: {
-                            type: 'string'
+                expect(definitionGenerator.openAPI.components.schemas).to.have.property('main')
+                expect(definitionGenerator.openAPI.components.schemas.main.properties).to.have.property('Error')
+                expect(definitionGenerator.openAPI.components.schemas.main.properties.Error).to.have.property('type')
+                expect(definitionGenerator.openAPI.components.schemas.main.properties.Error.type).to.be.equal('string')
+                expect(definitionGenerator.openAPI.components.schemas.main).to.not.have.property('$schema')
+                expect(definitionGenerator.openAPI.components.schemas.main).to.not.have.property('$definitions')
+                expect(expected).to.equal('#/components/schemas/main')
+
+                expect(spy.callCount).to.be.equal(2)
+
+                spy.resetHistory()
+            });
+
+            it('should add all schemas from a conversion to the components', async function() {
+                const complexSchema = {
+                    "$schema": "http://json-schema.org/draft-04/schema#",
+                    "title": "JSON API Schema",
+                    "description": "This is a blah blah for responses in the JSON API format. For more, see http://jsonapi.org",
+                    "type": "object",
+                    "properties": {
+                        "street_address": {
+                            "type": "string"
+                        },
+                        "country": {
+                            "type": "string",
+                            "default": "United States of America",
+                            "enum": [
+                                "United States of America",
+                                "Canada"
+                            ]
+                        }
+                    },
+                    "if": {
+                        "properties": {
+                            "country": {
+                                "const": "United States of America"
+                            }
+                        }
+                    },
+                    "then": {
+                        "properties": {
+                            "postal_code": {
+                                "pattern": "[0-9]{5}(-[0-9]{4})?"
+                            }
                         }
                     }
-                })
-                expect(expected).to.equal('#/components/schemas/simpleSchema')
+                }
+
+                const definitionGenerator = new DefinitionGenerator(mockServerless)
+                let expected = await definitionGenerator.schemaCreator(complexSchema, 'main')
+                    .catch((err) => {
+                        console.error(err)
+                    })
+
+                expect(expected).to.equal('#/components/schemas/main')
+                expect(definitionGenerator.openAPI.components.schemas).to.have.property('main')
+                expect(Object.keys(definitionGenerator.openAPI.components.schemas).length).to.be.equal(2)
+
             });
         });