serverless-openapi-documenter 0.0.40 → 0.0.42

package/README.md

@@ -14,7 +14,7 @@
 
 
 
-This will generate an OpenAPI V3 (up to v3.0.3) file for you from your serverless file.  It can optionally generate a Postman Collection V2 from the OpenAPI file for you too.
+This will generate an OpenAPI V3 (up to v3.0.3) file for you from your serverless file.  It can optionally generate a [Postman Collection V2](https://github.com/postmanlabs/openapi-to-postman) from the OpenAPI file for you too.
 
 Originally based off of: https://github.com/temando/serverless-openapi-documentation
 

package/package.json

@@ -1,17 +1,21 @@
 {
   "name": "serverless-openapi-documenter",
-  "version": "0.0.40",
+  "version": "0.0.42",
   "description": "Generate OpenAPI v3 documentation and Postman Collections from your Serverless Config",
   "main": "index.js",
   "keywords": [
     "serverless",
     "serverless2",
     "serverless3",
+    "serverless framework",
+    "serverless framework plugin",
+    "serverless plugin",
     "openAPI",
     "openAPIv3",
     "openAPI3",
     "PostmanCollections",
-    "Postman-Collections"
+    "Postman-Collections",
+    "Postman Collections"
   ],
   "scripts": {
     "test": "mocha --config './test/.mocharc.js'"
@@ -34,7 +38,7 @@
     "json-schema-for-openapi": "^0.3.1",
     "lodash.isequal": "^4.5.0",
     "oas-validator": "^5.0.8",
-    "openapi-to-postmanv2": "^4.4.1",
+    "openapi-to-postmanv2": "^4.6.0",
     "swagger2openapi": "^7.0.8",
     "uuid": "^9.0.0"
   },
@@ -44,6 +48,7 @@
   "devDependencies": {
     "chai": "^4.3.7",
     "mocha": "^10.2.0",
+    "nock": "^13.2.9",
     "sinon": "^15.0.0"
   }
 }

package/src/definitionGenerator.js

@@ -461,15 +461,21 @@ class DefinitionGenerator {
     }
 
     async dereferenceSchema(schema) {
-        let deReferencedSchema = await $RefParser.dereference(schema, this.refParserOptions)
+        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 = schema.$ref
+        if (deReferencedSchema?.$ref === '#') {
+            const oldRef = originalSchema.$ref
             const path = oldRef.split('/')
 
             const pathTitle = path[path.length-1]

package/test/unit/definitionGenerator.spec.js

@@ -4,6 +4,7 @@ const fs = require('fs').promises
 const path = require('path')
 const sinon = require('sinon')
 const $RefParser = require("@apidevtools/json-schema-ref-parser")
+const nock = require('nock')
 const expect = require('chai').expect
 
 const serverlessMock = require('../helpers/serverless')
@@ -948,10 +949,13 @@ describe('DefinitionGenerator', () => {
 
         describe('schemas that are urls', () => {
             it('should attempt to download a schema and convert it', async function() {
-                const simpleSchema = 'https:///google.com/build/LicensedMember.json'
+                const simpleSchema = 'https://google.com/build/LicensedMember.json'
                 const LicensedMemberJSON = require('../json/complex.json')
 
-                const stub = sinon.stub($RefParser, 'dereference').resolves(LicensedMemberJSON)
+                const scope = nock('https://google.com')
+                    .get('/build/LicensedMember.json')
+                    .reply(200, LicensedMemberJSON)
+
                 const definitionGenerator = new DefinitionGenerator(mockServerless)
                 const expected = await definitionGenerator.schemaCreator(simpleSchema, 'LicensedMember')
                     .catch((err) => {
@@ -963,28 +967,16 @@ describe('DefinitionGenerator', () => {
                 expect(definitionGenerator.openAPI.components.schemas.LicensedMember.properties).to.have.property('template')
                 expect(definitionGenerator.openAPI.components.schemas.LicensedMember.properties).to.have.property('database')
                 expect(expected).to.equal('#/components/schemas/LicensedMember')
-
-                stub.restore()
             });
 
             it('should take a mix of schemas', async function() {
-                const complexSchema = 'https:///google.com/build/LicensedMember.json'
+                const complexSchema = 'https://google.com/build/LicensedMember.json'
                 const LicensedMemberJSON = require('../json/complex.json')
 
-                // const stub = sinon.stub($RefParser, 'dereference').resolves(LicensedMemberJSON)
-                const stub = sinon.stub($RefParser, 'dereference')
-                    .onFirstCall().resolves(LicensedMemberJSON)
-                    .onSecondCall().resolves({
-                        type: "object",
-                        properties: {
-                            UUID: {
-                                $ref: "#/definitions/log"
-                            },
-                            name: {
-                                type: "string"
-                            }
-                        }
-                    })
+                const scope = nock('https://google.com')
+                    .get('/build/LicensedMember.json')
+                    .reply(200, LicensedMemberJSON)
+
                 const definitionGenerator = new DefinitionGenerator(mockServerless)
                 let expected = await definitionGenerator.schemaCreator(complexSchema, 'LicensedMember')
                     .catch((err) => {
@@ -1007,35 +999,65 @@ describe('DefinitionGenerator', () => {
 
                 expected = await definitionGenerator.schemaCreator(simpleSchema, 'simpleSchema')
                     .catch((err) => {
+                        expect(err).to.be.an('error')
                         console.error(err)
                     })
 
+                expect(expected).to.be.undefined
                 expect(definitionGenerator.openAPI.components.schemas).to.have.property('LicensedMember')
                 expect(definitionGenerator.openAPI.components.schemas.LicensedMember.properties).to.have.property('log')
                 expect(definitionGenerator.openAPI.components.schemas.LicensedMember.properties).to.have.property('template')
                 expect(definitionGenerator.openAPI.components.schemas.LicensedMember.properties).to.have.property('database')
-                expect(definitionGenerator.openAPI.components.schemas).to.have.property('simpleSchema')
-                expect(definitionGenerator.openAPI.components.schemas.simpleSchema.properties).to.have.property('UUID')
-                expect(definitionGenerator.openAPI.components.schemas.simpleSchema.properties).to.have.property('name')
-                expect(expected).to.equal('#/components/schemas/simpleSchema')
-
-                stub.restore()
             });
 
             it('should throw an error when a url can not be resolved', async function() {
-                const simpleSchema = 'https:///google.com/build/LicensedMember.json'
+                const simpleSchema = 'https://google.com/build/LicensedMember.json'
+
+                const scope = nock('https://google.com')
+                    .get('/build/LicensedMember.json')
+                    .reply(404)
 
-                const stub = sinon.stub($RefParser, 'dereference').rejects(new Error())
                 const definitionGenerator = new DefinitionGenerator(mockServerless)
                 const expected = await definitionGenerator.schemaCreator(simpleSchema, 'simpleSchema')
                     .catch((err) => {
-                        console.error(err)
                         expect(err).to.be.an('error')
                     })
 
                 expect(expected).to.be.undefined
+            });
 
-                stub.restore()
+            it('should handle a poorly dereferenced schema', async function() {
+                const simpleSchema = 'https://google.com/build/LicensedMember.json'
+
+                const externalSchema = {
+                    $schema: 'http://json-schema.org/draft-04/schema#',
+                    title: 'JSON API Schema',
+                    $ref: '#/definitions/Error',
+                    definitions: {
+                        Error: {
+                            type: 'string'
+                        }
+                    }
+                }
+
+                const scope = nock('https://google.com')
+                    .get('/build/LicensedMember.json')
+                    .reply(200, externalSchema)
+
+
+                const definitionGenerator = new DefinitionGenerator(mockServerless)
+                const expected = await definitionGenerator.schemaCreator(simpleSchema, 'LicensedMember')
+                    .catch((err) => {
+                        console.error(err)
+                    })
+
+                expect(definitionGenerator.openAPI.components.schemas).to.have.property('LicensedMember')
+                expect(definitionGenerator.openAPI.components.schemas.LicensedMember.properties).to.have.property('Error')
+                expect(definitionGenerator.openAPI.components.schemas.LicensedMember.properties.Error).to.have.property('type')
+                expect(definitionGenerator.openAPI.components.schemas.LicensedMember.properties.Error.type).to.be.equal('string')
+                expect(definitionGenerator.openAPI.components.schemas.LicensedMember).to.not.have.property('$schema')
+                expect(definitionGenerator.openAPI.components.schemas.LicensedMember).to.not.have.property('$definitions')
+                expect(expected).to.equal('#/components/schemas/LicensedMember')
             });
         });
     });