serverless-openapi-documenter 0.0.5 → 0.0.8

package/README.md

@@ -1,5 +1,14 @@
 # OpenAPI Generator for serverless
 
+<p>
+  <a href="https://www.serverless.com">
+    <img src="http://public.serverless.com/badges/v3.svg">
+  </a>
+  <a href="https://www.npmjs.com/package/serverless-openapi-documenter">
+    <img src="https://img.shields.io/npm/v/serverless-openapi-documenter.svg?style=flat-square">
+  </a>
+</p>
+
 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.
 
 Originally based off of: https://github.com/temando/serverless-openapi-documentation
@@ -47,13 +56,17 @@ Options:
 | info.version             | custom.documentation.version  OR  random v4 uuid if not provided                   |
 | externalDocs.description | custom.documentation.externalDocumentation.description                             |
 | externalDocs.url         | custom.documentation.externalDocumentation.url                                     |
-| servers[].description      | custom.documentation.servers.description                                           |
-| servers[].url              | custom.documentation.servers.url                                                   |
+| servers[].description      | custom.documentation.servers.description                                         |
+| servers[].url              | custom.documentation.servers.url                                                 |
+| tags[].name                     | custom.documentation.tags.name                                              |
+| tags[].description              | custom.documentation.tags.description                                       |
+| tags[].externalDocs.url         | custom.documentation.tags.externalDocumentation.url                         |
+| tags[].externalDocs.description | custom.documentation.tags.externalDocumentation.description                 |
 | path[path]         | functions.functions.events.[http OR httpApi].path                                        |
 | path[path].summary         | functions.functions.summary                                                      |
 | path[path].description         | functions.functions.description                                              |
-| path[path].servers[].description      | functions.functions.servers.description                                           |
-| path[path].servers[].url              | functions.functions.servers.url                                                   |
+| path[path].servers[].description      | functions.functions.servers.description                               |
+| path[path].servers[].url              | functions.functions.servers.url                                       |
 | path[path].[operation]         | functions.functions.[http OR httpApi].method                                 |
 | path[path].[operation].summary             | functions.functions.[http OR httpApi].documentation.summary      |
 | path[path].[operation].description         | functions.functions.[http OR httpApi].documentation.description  |
@@ -106,6 +119,12 @@ custom:
     servers:
       url: https://example.com
       description: The server
+    tags:
+      - name: tag1
+        description: this is a tag
+        externalDocumentation:
+          url: https://npmjs.com
+          description: A link to npm
 ```
 
 These configurations can be quite verbose; you can separate it out into it's own file, such as `serverless.doc.yml` as below:
@@ -134,7 +153,7 @@ The *required* directives for the models section are as follow:
 * `name`: the name of the schema
 * `description`: a description of the schema
 * `contentType`: the content type of the described request/response (ie. `application/json` or `application/xml`).
-* `schema`: The JSON Schema ([website](http://json-schema.org/)) that describes the model. You can either use inline `YAML` to define these, or refer to an external schema file as below
+* `schema`: The JSON Schema ([website](http://json-schema.org/)) that describes the model. You can either use inline `YAML` to define these or use either an external file schema that serverless will resolve (as below), or a reference to an externally hosted schema that will be attempted to be resolved.
 
 ```yml
 custom:
@@ -195,6 +214,8 @@ functions:
         documentation:
           summary: "Create User"
           description: "Creates a user and then sends a generated password email"
+          tags:
+            - tag1
           externalDocumentation:
             url: https://bing.com
             description: A link to bing
@@ -241,7 +262,7 @@ Query 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)
-* `schema`: JSON schema (inline or file)
+* `schema`: JSON schema (inline, file or externally hosted)
 
 ```yml
 queryParams:
@@ -258,7 +279,7 @@ Path parameters can be described as follow:
 
 * `name`: the name of the query variable
 * `description`: a description of the query variable
-* `schema`: JSON schema (inline or file)
+* `schema`: JSON schema (inline, file or externally hosted)
 
 ```yml
 pathParams:
@@ -275,7 +296,7 @@ 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)
-* `schema`: JSON schema (inline or file)
+* `schema`: JSON schema (inline, file or externally hosted)
 
 ```yml
 cookieParams:
@@ -333,7 +354,7 @@ The attributes for a header are as follow:
 
 * `name`: the name of the HTTP Header
 * `description`: a description of the HTTP Header
-* `schema`: JSON schema (inline or file)
+* `schema`: JSON schema (inline, file or externally hosted)
 
 ```yml
 responseHeaders:
@@ -352,6 +373,82 @@ requestHeaders:
 
 Please view the example [serverless.yml](test/serverless\ 2/serverless.yml).
 
+## Notes on schemas
+
+Schemas can be either: inline, in file or externally hosted.  If they're inline or in file, the plugin will attempt to normalise the schema to [OpenAPI 3.0.X specification](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.0.0.md#schemaObject).  
+
+If they exist as an external reference, for instance:
+
+```yaml
+schema: https://raw.githubusercontent.com/SchemaStore/schemastore/master/src/schemas/json/bettercodehub.json
+```
+
+We use the plugin [JSON Schema $Ref Parser](https://apitools.dev/json-schema-ref-parser/) to attempt to parse and resolve the references.  There are limitations to this.  Consider the schema:
+
+```json
+{
+    "$schema": "https://json-schema.org/draft-04/schema",
+    "title": "Reusable Definitions",
+    "type": "object",
+    "id": "https://raw.githubusercontent.com/json-editor/json-editor/master/tests/fixtures/definitions.json",
+    "definitions": {
+        "address": {
+            "title": "Address",
+            "type": "object",
+            "properties": {
+                "street_address": { "type": "string" },
+                "city":           { "type": "string" },
+                "state":          { "type": "string" }
+            },
+            "required": ["street_address"]
+        },
+        "link" : {"$refs": "./properties.json#/properties/title"}
+    },
+    "properties": {
+        "address" : {"$refs": "#/definitions/address"}
+    }
+  }
+```
+Where the definition "link" refers to a schema held in a directory that the resolver does not know about, we will not be able to fully resolve the schema which will likely cause errors in validation of the openAPI 3.0.X specification.
+
+Because of the dependency we use to parse externally linked schemas, we can supply our own options to resolve schemas that are more difficult than a straight forward example.
+
+You can create your own options file: https://apitools.dev/json-schema-ref-parser/docs/options.html to pass into the dependency that contains it's own resolver to allow you to resolve references that might be in hard to reach places.  In your main project folder, you should have a folder called `options` with a file called `ref-parser.js` that looks like:
+
+```js
+'use strict'
+
+// options from: https://apitools.dev/json-schema-ref-parser/docs/options.html
+
+module.exports = {
+  continueOnError: true,            // Don't throw on the first error
+  parse: {
+    json: false,                    // Disable the JSON parser
+    yaml: {
+      allowEmpty: false             // Don't allow empty YAML files
+    },
+    text: {
+      canParse: [".txt", ".html"],  // Parse .txt and .html files as plain text (strings)
+      encoding: 'utf16'             // Use UTF-16 encoding
+    }
+  },
+  resolve: {
+    file: false,                    // Don't resolve local file references
+    http: {
+      timeout: 2000,                // 2 second timeout
+      withCredentials: true,        // Include auth credentials when resolving HTTP references
+    }
+  },
+  dereference: {
+    circular: false,                // Don't allow circular $refs
+    excludedPathMatcher: (path) =>  // Skip dereferencing content under any 'example' key
+      path.includes("/example/")
+  }
+}
+```
+
+If you don't supply this file, it will use the default options.
+
 ## License
 
 MIT

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "serverless-openapi-documenter",
-  "version": "0.0.5",
+  "version": "0.0.8",
   "description": "Generate OpenAPI v3 documentation and Postman Collections from your Serverless Config",
   "main": "index.js",
   "keywords": [
@@ -28,12 +28,16 @@
   },
   "license": "MIT",
   "dependencies": {
+    "@apidevtools/json-schema-ref-parser": "^9.0.9",
     "chalk": "^4.1.2",
     "js-yaml": "^4.1.0",
-    "json-schema-for-openapi": "^0.1.0",
+    "json-schema-for-openapi": "^0.1.2",
     "oas-validator": "^5.0.8",
     "openapi-to-postmanv2": "^3.2.0",
     "swagger2openapi": "^7.0.8",
     "uuid": "^8.3.2"
+  },
+  "engines": {
+    "node": ">=14"
   }
 }

package/src/definitionGenerator.js

@@ -1,8 +1,11 @@
 'use strict'
 
+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");
 
 class DefinitionGenerator {
     constructor(serverless, options = {}) {
@@ -24,16 +27,35 @@ class DefinitionGenerator {
         }
 
         this.operationIds = []
+
+        try {
+            this.refParserOptions = require(path.resolve('options', 'ref-parser.js'))
+        } catch (err) {
+            this.refParserOptions = {}
+        }
+        
     }
 
-    parse() {
+    async parse() {
         this.createInfo()
-        this.createPaths()
+        await this.createPaths()
+            .catch(err => {
+                throw err
+            })
+        
         if (this.serverless.service.custom.documentation.servers) {
             const servers = this.createServers(this.serverless.service.custom.documentation.servers)
             Object.assign(this.openAPI, {servers: servers})
         }
-        this.createExternalDocumentation()
+
+        if (this.serverless.service.custom.documentation.tags) {
+            this.createTags()
+        }
+
+        if (this.serverless.service.custom.documentation.externalDocumentation) {
+            const extDoc = this.createExternalDocumentation(this.serverless.service.custom.documentation.externalDocumentation)
+            Object.assign(this.openAPI, {externalDocs: extDoc})
+        }
     }
 
     createInfo() {
@@ -48,7 +70,7 @@ class DefinitionGenerator {
         Object.assign(this.openAPI, {info})
     }
 
-    createPaths() {
+    async createPaths() {
         const paths = {}
         const httpFunctions = this.getHTTPFunctions()
 
@@ -65,7 +87,11 @@ class DefinitionGenerator {
                         opId = `${httpFunction.functionInfo.name}-${uuid()}`
                     }
 
-                    const path = this.createOperationObject(event.http.method || event.httpApi.method, documentation, opId)
+                    const path = await this.createOperationObject(event.http.method || event.httpApi.method, documentation, opId)
+                        .catch(err => {
+                            throw err
+                        })
+                    
                     if (httpFunction.functionInfo?.summary)
                         path.summary = httpFunction.functionInfo.summary
 
@@ -121,14 +147,35 @@ class DefinitionGenerator {
         return newServers
     }
 
-    createExternalDocumentation() {
-        const documentation = this.serverless.service.custom.documentation
-        if (documentation.externalDocumentation) {
-            Object.assign(this.openAPI, {externalDocs: {...documentation.externalDocumentation}})
+    createExternalDocumentation(docs) {
+        return {...docs}
+        // const documentation = this.serverless.service.custom.documentation
+        // if (documentation.externalDocumentation) {
+        //     // Object.assign(this.openAPI, {externalDocs: {...documentation.externalDocumentation}})
+        //     return 
+        // }
+    }
+
+    createTags() {
+        const tags = []
+        for (const tag of this.serverless.service.custom.documentation.tags) {
+            const obj = {
+                name: tag.name,
+            }
+
+            if (tag.description) {
+                obj.description = tag.description
+            }
+
+            if (tag.externalDocumentation) {
+                obj.externalDocs = this.createExternalDocumentation(tag.externalDocumentation)
+            }
+            tags.push(obj)
         }
+        Object.assign(this.openAPI, {tags: tags})
     }
 
-    createOperationObject(method, documentation, name = uuid()) {
+    async createOperationObject(method, documentation, name = uuid()) {
         const obj = {
             summary: documentation.summary || '',
             description: documentation.description || '',
@@ -138,22 +185,34 @@ class DefinitionGenerator {
         }
 
         if (documentation.pathParams) {
-            const paramObject = this.createParamObject('path', documentation)
+            const paramObject = await this.createParamObject('path', documentation)
+                .catch(err => {
+                    throw err
+                })
             obj.parameters = obj.parameters.concat(paramObject)
         }
 
         if (documentation.queryParams) {
-            const paramObject = this.createParamObject('query', documentation)
+            const paramObject = await this.createParamObject('query', documentation)
+                .catch(err => {
+                    throw err
+                })
             obj.parameters = obj.parameters.concat(paramObject)
         }
 
         if (documentation.headerParams) {
-            const paramObject = this.createParamObject('header', documentation)
+            const paramObject = await this.createParamObject('header', documentation)
+                .catch(err => {
+                    throw err
+                })
             obj.parameters = obj.parameters.concat(paramObject)
         }
 
         if (documentation.cookieParams) {
-            const paramObject = this.createParamObject('cookie', documentation)
+            const paramObject = await this.createParamObject('cookie', documentation)
+                .catch(err => {
+                    throw err
+                })
             obj.parameters = obj.parameters.concat(paramObject)
         }
 
@@ -165,10 +224,16 @@ class DefinitionGenerator {
             obj.deprecated = documentation.deprecated
 
         if (documentation.requestBody)
-            obj.requestBody = this.createRequestBody(documentation)
+            obj.requestBody = await this.createRequestBody(documentation)
+                .catch(err => {
+                    throw err
+                })
 
         if (documentation.methodResponses)
-            obj.responses = this.createResponses(documentation)
+            obj.responses = await this.createResponses(documentation)
+                .catch(err => {
+                    throw err
+                })
 
         if (documentation.servers) {
             const servers = this.createServers(documentation.servers)
@@ -178,14 +243,17 @@ class DefinitionGenerator {
         return {[method]: obj}
     }
 
-    createResponses(documentation) {
+    async createResponses(documentation) {
         const responses = {}
         for (const response of documentation.methodResponses) {
             const obj = {
                 description: response.responseBody.description || '',
             }
 
-            obj.content = this.createMediaTypeObject(response.responseModels, 'responses')
+            obj.content = await this.createMediaTypeObject(response.responseModels, 'responses')
+                .catch(err => {
+                    throw err
+                })
 
             Object.assign(responses,{[response.statusCode]: obj})
         }
@@ -193,18 +261,21 @@ class DefinitionGenerator {
         return responses
     }
 
-    createRequestBody(documentation) {
+    async createRequestBody(documentation) {
         const obj = {
             description: documentation.requestBody.description,
             required: documentation.requestBody.required || false,
         }
 
-        obj.content = this.createMediaTypeObject(documentation.requestModels, 'requestBody')
+        obj.content = await this.createMediaTypeObject(documentation.requestModels, 'requestBody')
+            .catch(err => {
+                throw err
+            })
 
         return obj
     }
 
-    createMediaTypeObject(models, type) {
+    async createMediaTypeObject(models, type) {
         const mediaTypeObj = {}
         for (const mediaTypeDocumentation of this.serverless.service.custom.documentation.models) {
             if (Object.values(models).includes(mediaTypeDocumentation.name)) {
@@ -222,59 +293,12 @@ class DefinitionGenerator {
                     obj.examples = this.createExamples(mediaTypeDocumentation.examples)
 
                 if (mediaTypeDocumentation.content[contentKey].schema) {
-                    const schema = SchemaConvertor.convert(mediaTypeDocumentation.content[contentKey].schema)
-                    for (const key of Object.keys(schema.schemas)) {
-                        if (key === 'main' || key.split('-')[0] === 'main') {
-                            obj.schema = {
-                                $ref: `#/components/schemas/${mediaTypeDocumentation.name}`
-                            }
-
-                            if (this.openAPI?.components) {
-                                if (this.openAPI.components?.schemas) {
-                                    const schemaObj = {
-                                        [mediaTypeDocumentation.name]: schema.schemas[key]
-                                    }
-                                    Object.assign(this.openAPI.components.schemas, schemaObj)
-                                } else {
-                                    const schemaObj = {
-                                        [mediaTypeDocumentation.name]: schema.schemas[key]
-                                    }
-                                    Object.assign(this.openAPI.components, {schemas: schemaObj})
-                                }
-                            } else {
-                                const components = {
-                                    components: {
-                                        schemas: {
-                                            [mediaTypeDocumentation.name]: schema.schemas[key]
-                                        }
-                                    }
-                                }
-                                Object.assign(this.openAPI, components)
-                            }
-                        } else {
-                            if (this.openAPI?.components) {
-                                if (this.openAPI.components?.schemas) {
-                                    const schemaObj = {
-                                        [key]: schema.schemas[key]
-                                    }
-                                    Object.assign(this.openAPI.components.schemas, schemaObj)
-                                } else {
-                                    const schemaObj = {
-                                        [key]: schema.schemas[key]
-                                    }
-                                    Object.assign(this.openAPI.components, {schemas: schemaObj})
-                                }
-                            } else {
-                                const components = {
-                                    components: {
-                                        schemas: {
-                                            [key]: schema.schemas[key]
-                                        }
-                                    }
-                                }
-                                Object.assign(this.openAPI, components)
-                            }
-                        }
+                    const schemaRef = await this.schemaCreator(mediaTypeDocumentation.content[contentKey].schema, mediaTypeDocumentation.name)
+                        .catch(err => {
+                            throw err
+                        })
+                    obj.schema = {
+                        $ref: schemaRef
                     }
                 }
 
@@ -284,7 +308,7 @@ class DefinitionGenerator {
         return mediaTypeObj
     }
 
-    createParamObject(paramIn, documentation) {
+    async createParamObject(paramIn, documentation) {
         const params = []
         for (const param of documentation[`${paramIn}Params`]) {
             const obj = {
@@ -305,7 +329,7 @@ class DefinitionGenerator {
             if (param.style)
                 obj.style = param.style
 
-            if (param.explode)
+            if (Object.keys(param).includes('explode'))
                 obj.explode = param.explode
 
             if (paramIn === 'query' && param.allowReserved)
@@ -318,10 +342,12 @@ class DefinitionGenerator {
                 obj.examples = this.createExamples(param.examples)
 
             if (param.schema) {
-                const schema = SchemaConvertor.convert(param.schema)
-                if (schema.schemas.main) {
-                    Object.assign(obj,{schema: schema.schemas.main})
-
+                const schemaRef = await this.schemaCreator(param.schema, param.name)
+                    .catch(err => {
+                        throw err
+                    })
+                obj.schema = {
+                    $ref: schemaRef
                 }
             }
 
@@ -330,6 +356,55 @@ class DefinitionGenerator {
         return params;
     }
 
+    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)
+            }
+        }
+
+        if (typeof schema !== 'string' && Object.keys(schema).length > 0) {
+            const convertedSchema = SchemaConvertor.convert(schema)
+            for (const key of Object.keys(convertedSchema.schemas)) {
+                if (key === 'main' || key.split('-')[0] === 'main') {
+                    const ref = `#/components/schemas/${name}`
+
+                    addToComponents(convertedSchema.schemas[key], name)
+                    return ref
+                } else {
+                    addToComponents(convertedSchema.schemas[key], key)
+                }
+            }
+        } else {
+            const combinedSchema = await $RefParser.dereference(schema, this.refParserOptions)
+                .catch(err => {
+                    console.error(err)
+                    throw err
+                })
+
+            return await this.schemaCreator(combinedSchema, name)
+                .catch(err => {
+                    throw err
+                })
+        }
+    }
+
     createExamples(examples) {
         const examplesObj = {}
 

package/src/openAPIGenerator.js

@@ -67,11 +67,18 @@ class OpenAPIGenerator {
           required: ['documentation'],
         });
 
+        this.serverless.configSchemaHandler.defineFunctionEventProperties('aws', 'httpApi', {
+          properties: {
+            documentation: { type: 'object' },
+          },
+          required: ['documentation'],
+        });
+
         this.serverless.configSchemaHandler.defineFunctionProperties('aws', {
           properties: {
             // description: {type: 'string'},
             summary: {type: 'string'},
-            servers: {type: ['object', 'array']},
+            servers: {anyOf: [{type:'object'}, {type:'array'}]},
           }
         })
     }
@@ -97,12 +104,15 @@ class OpenAPIGenerator {
         const config = this.processCliInput()
         const generator = new DefinitionGenerator(this.serverless);
 
-        generator.parse();
+        await generator.parse()
+          .catch(err => {
+            this.log('error', chalk.bold.red(`ERROR: An error was thrown generating the OpenAPI v3 documentation`))
+            throw new this.serverless.classes.Error(err)
+          })
 
         const valid = await generator.validate()
           .catch(err => {
-
-            this.log('error', chalk.bold.red(`ERROR: An error was thrown generation the OpenAPI v3 documentation`))
+            this.log('error', chalk.bold.red(`ERROR: An error was thrown validating the OpenAPI v3 documentation`))
             throw new this.serverless.classes.Error(err)
           })
 

package/test/serverless 2/serverless.yml

@@ -19,6 +19,8 @@ functions:
           documentation:
             summary: Create User
             description: Creates a user and then sends a generated password email
+            tags: 
+              - jesus
             externalDocumentation:
               url: https://bing.com
               description: A link to bing
@@ -67,6 +69,12 @@ custom:
   documentation:
     description: This is a description of what this does
     version: 1.0.0
+    tags: 
+      - name: jesus
+        description: jesus was a man
+        externalDocumentation:
+          url: https://whitehouse.gov
+          description: a link to the whitehouse
     externalDocumentation:
       url: https://google.com
       description: A link to google