serverless-openapi-documenter 0.0.26 → 0.0.30

package/.github/workflows/node.yml

@@ -16,7 +16,7 @@ jobs:
 
     strategy:
       matrix:
-        node-version: [14.x, 16.x]
+        node-version: [14.x, 16.x, 18.x]
         # See supported Node.js release schedule at https://nodejs.org/en/about/releases/
 
     steps:

package/README.md

@@ -63,6 +63,7 @@ Options:
 | externalDocs.url         | custom.documentation.externalDocumentation.url                                     |
 | servers[].description      | custom.documentation.servers.description                                         |
 | servers[].url              | custom.documentation.servers.url                                                 |
+| servers[].variables              | custom.documentation.servers.variables                                     |
 | tags[].name                     | custom.documentation.tags.name                                              |
 | tags[].description              | custom.documentation.tags.description                                       |
 | tags[].externalDocs.url         | custom.documentation.tags.externalDocumentation.url                         |
@@ -121,8 +122,15 @@ custom:
       url: https://google.com
       description: A link to google
     servers:
-      url: https://example.com
+      url: https://example.com:{port}/
       description: The server
+      variables:
+        port:
+          enum: 
+            - 4000
+            - 3000
+          default: 3000
+          description: The port the server operates on
     tags:
       - name: tag1
         description: this is a tag
@@ -222,6 +230,39 @@ custom:
                       type: "string"
 ```
 
+##### Model re-use
+
+Through the magic of YAML, you can re-use models:
+
+```yml
+custom:
+  documentation:
+    ...
+    models:
+      - name: "ErrorResponse"
+        description: "This is an error"
+        content:
+          application/json:
+            schema: &ErrorItem
+            type: object
+            properties:
+              message: 
+                type: string
+              code:
+                type: integer
+                  
+      - name: "PutDocumentResponse"
+        description: "PUT Document response model (external reference example)"
+        content:
+          application/json:
+            schema: 
+            type: array
+            items: *ErrorItem
+```
+
+`&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.
+
+
 #### Functions
 
 To define the documentation for a given function event, you need to create a `documentation` attribute for your http event in your `serverless.yml` file.
@@ -238,6 +279,7 @@ The `documentation` section of the event configuration can contain the following
 * `queryParams`: a list of query parameters (see [queryParams](#queryparams) below)
 * `pathParams`: a list of path parameters (see [pathParams](#pathparams) below)
 * `cookieParams`: a list of cookie parameters (see [cookieParams](#cookieparams) below)
+* `headerParams`: a list of headers (see [headerParams](#headerparams---request-headers) below)
 * `methodResponses`: an array of response models and applicable status codes
   * `statusCode`: applicable http status code (ie. 200/404/500 etc.)
   * `responseBody`: contains description of the response
@@ -285,12 +327,22 @@ functions:
               description: "A Session ID variable"
               schema:
                 type: "string"
+          headerParams:
+            name: "Content-Type"
+            description: "The content type"
+            schema:
+              type: "string"
           methodResponses:
             - statusCode: 201
               responseBody:
                 description: "A user object along with generated API Keys"
               responseModels:
                 application/json: "PutDocumentResponse"
+              responseHeaders:
+                X-Rate-Limit-Limit:
+                  description: The number of allowed requests in the current period
+                  schema:
+                    type: integer
             - statusCode: 500
               responseBody:
                 description: "An error message when creating a new user"
@@ -320,8 +372,8 @@ queryParams:
 
 Path parameters can be described as follow:
 
-* `name`: the name of the query variable
-* `description`: a description of the query variable
+* `name`: the name of the path parameter
+* `description`: a description of the path parameter
 * `schema`: JSON schema (inline, file or externally hosted)
 
 ```yml
@@ -336,9 +388,9 @@ pathParams:
 
 Cookie parameters can be described as follow:
 
-* `name`: the name of the query variable
-* `description`: a description of the query variable
-* `required`: whether the query parameter is mandatory (boolean)
+* `name`: the name of the cookie parameter
+* `description`: a description of the cookie parameter
+* `required`: whether the cookie parameter is mandatory (boolean)
 * `schema`: JSON schema (inline, file or externally hosted)
 
 ```yml
@@ -354,9 +406,9 @@ cookieParams:
 
 Request Headers can be described as follow:
 
-* `name`: the name of the query variable
-* `description`: a description of the query variable
-* `required`: whether the query parameter is mandatory (boolean)
+* `name`: the name of the header
+* `description`: a description of the header
+* `required`: whether the header is mandatory (boolean)
 * `schema`: JSON schema (inline, file or externally hosted)
 
 ```yml

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "serverless-openapi-documenter",
-  "version": "0.0.26",
+  "version": "0.0.30",
   "description": "Generate OpenAPI v3 documentation and Postman Collections from your Serverless Config",
   "main": "index.js",
   "keywords": [
@@ -28,21 +28,21 @@
   },
   "license": "MIT",
   "dependencies": {
-    "@apidevtools/json-schema-ref-parser": "^9.0.9",
+    "@apidevtools/json-schema-ref-parser": "^9.1.0",
     "chalk": "^4.1.2",
     "js-yaml": "^4.1.0",
-    "json-schema-for-openapi": "^0.2.1",
+    "json-schema-for-openapi": "^0.3.0",
     "oas-validator": "^5.0.8",
-    "openapi-to-postmanv2": "^4.1.0",
+    "openapi-to-postmanv2": "^4.4.1",
     "swagger2openapi": "^7.0.8",
-    "uuid": "^8.3.2"
+    "uuid": "^9.0.0"
   },
   "engines": {
     "node": ">=14"
   },
   "devDependencies": {
-    "chai": "^4.3.6",
-    "mocha": "^10.0.0",
-    "sinon": "^14.0.0"
+    "chai": "^4.3.7",
+    "mocha": "^10.1.0",
+    "sinon": "^15.0.0"
   }
 }

package/src/definitionGenerator.js

@@ -410,6 +410,14 @@ class DefinitionGenerator {
         return params;
     }
 
+    async dereferenceSchema(schema) {
+        return await $RefParser.dereference(schema, this.refParserOptions)
+            .catch(err => {
+                console.error(err)
+                throw err
+            })
+    }
+
     async schemaCreator(schema, name) {
         const addToComponents = (schema, name) => {
             const schemaObj = {
@@ -433,14 +441,27 @@ class DefinitionGenerator {
             }
         }
 
-        const deReferencedSchema = await $RefParser.dereference(schema, this.refParserOptions)
-            .catch(err => {
-                console.error(err)
+        let deReferencedSchema = await this.dereferenceSchema(schema)
+            .catch((err) => {
                 throw err
             })
 
+        // deal with schemas that have been de-referenced poorly
+        if (deReferencedSchema.$ref === '#') {
+            const oldRef = schema.$ref
+            const path = oldRef.split('/')
+
+            const pathTitle = path[path.length-1]
+            const property = deReferencedSchema.definitions[path[path.length-1]]
+            Object.assign(deReferencedSchema, {properties: {[pathTitle]: property}})
+            delete deReferencedSchema.$ref
+            deReferencedSchema = await this.dereferenceSchema(deReferencedSchema)
+                .catch((err) => {
+                    throw err
+                })
+        }
 
-        const convertedSchema = SchemaConvertor.convert(deReferencedSchema)
+        const convertedSchema = SchemaConvertor.convert(deReferencedSchema, name)
         let schemaName = name
         if (this.schemaIDs.includes(schemaName))
             schemaName = `${name}-${uuid()}`
@@ -448,7 +469,7 @@ class DefinitionGenerator {
         this.schemaIDs.push(schemaName)
 
         for (const key of Object.keys(convertedSchema.schemas)) {
-            if (key === 'main' || key.split('-')[0] === 'main') {
+            if (key === name || key.split('-')[0] === name) {
                 let ref = `#/components/schemas/`
 
                 if (this.openAPI?.components?.schemas?.[name]) {

package/test/unit/definitionGenerator.spec.js

@@ -458,6 +458,35 @@ describe('DefinitionGenerator', () => {
                 expect(definitionGenerator.openAPI.components.schemas).to.have.property('ContactPutRequest')
                 expect(expected).to.equal('#/components/schemas/ContactPutRequest')
             });
+
+            it('should handle a schema that has been improperly dereferenced', async function() {
+                const simpleSchema = {
+                    $schema: 'http://json-schema.org/draft-04/schema#',
+                    title: 'JSON API Schema',
+                    $ref: '#/definitions/Error',
+                    definitions: {
+                        Error: {
+                            type: 'string'
+                        }
+                    }
+                }
+                const definitionGenerator = new DefinitionGenerator(mockServerless)
+                const expected = await definitionGenerator.schemaCreator(simpleSchema, 'simpleSchema')
+                    .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(expected).to.equal('#/components/schemas/simpleSchema')
+            });
         });
 
         describe('schemas that are urls', () => {
@@ -473,9 +502,9 @@ describe('DefinitionGenerator', () => {
                     })
 
                 expect(definitionGenerator.openAPI.components.schemas).to.have.property('LicensedMember')
-                expect(definitionGenerator.openAPI.components.schemas).to.have.property('log')
-                expect(definitionGenerator.openAPI.components.schemas).to.have.property('template')
-                expect(definitionGenerator.openAPI.components.schemas).to.have.property('database')
+                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(expected).to.equal('#/components/schemas/LicensedMember')
 
                 stub.restore()
@@ -485,13 +514,27 @@ describe('DefinitionGenerator', () => {
                 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').resolves(LicensedMemberJSON)
+                const stub = sinon.stub($RefParser, 'dereference')
+                    .onFirstCall().resolves(LicensedMemberJSON)
+                    .onSecondCall().resolves({
+                        type: "object",
+                        properties: {
+                            UUID: {
+                                $ref: "#/definitions/log"
+                            },
+                            name: {
+                                type: "string"
+                            }
+                        }
+                    })
                 const definitionGenerator = new DefinitionGenerator(mockServerless)
                 let expected = await definitionGenerator.schemaCreator(complexSchema, 'LicensedMember')
                     .catch((err) => {
                         console.error(err)
                     })
 
+                // this will fail validation due to a missing definition
                 const simpleSchema = {
                     type: "object",
                     properties: {
@@ -511,10 +554,12 @@ describe('DefinitionGenerator', () => {
                     })
 
                 expect(definitionGenerator.openAPI.components.schemas).to.have.property('LicensedMember')
-                expect(definitionGenerator.openAPI.components.schemas).to.have.property('log')
-                expect(definitionGenerator.openAPI.components.schemas).to.have.property('template')
-                expect(definitionGenerator.openAPI.components.schemas).to.have.property('database')
+                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()
@@ -528,6 +573,7 @@ describe('DefinitionGenerator', () => {
                 const expected = await definitionGenerator.schemaCreator(simpleSchema, 'simpleSchema')
                     .catch((err) => {
                         console.error(err)
+                        expect(err).to.be.an('error')
                     })
 
                 expect(expected).to.be.undefined