serverless-openapi-documenter 0.0.1

package/src/definitionGenerator.js

@@ -0,0 +1,304 @@
+'use strict'
+
+const { v4: uuid } = require('uuid')
+const validator = require('oas-validator');
+const SchemaConvertor = require('json-schema-for-openapi')
+
+class DefinitionGenerator {
+    constructor(serverless, options = {}) {
+        this.version = options.v || '3.0.0'
+
+        this.serverless = serverless
+        this.httpKeys = {
+            http: 'http',
+            httpAPI: 'httpApi',
+        }
+
+        this.componentsSchemas = {
+            requestBody: 'requestBodies',
+            responses: 'responses',
+        }
+
+        this.openAPI = {
+            openapi: this.version,
+        }
+    }
+
+    parse() {
+        this.createInfo()
+        this.createPaths()
+    }
+
+    createInfo() {
+        const service = this.serverless.service
+        const documentation = this.serverless.service.custom.documentation;
+
+        const info = {
+            title: service.service,
+            description: documentation?.description || '',
+            version: documentation?.version || uuid(),
+        }
+        Object.assign(this.openAPI, {info})
+    }
+
+    createPaths() {
+        const paths = {}
+        const httpFunctions = this.getHTTPFunctions()
+
+        for (const httpFunction of httpFunctions) {
+            for (const event of httpFunction.event) {
+                if (event?.http?.documentation || event?.httpApi?.documentation) {
+                    const documentation = event.http.documentation || event.httpApi.documentation
+
+                    const path = this.createOperationObject(event.http.method || event.httpApi.method, documentation, httpFunction.functionInfo.name)
+                    if (httpFunction.functionInfo?.summary)
+                        path.summary = httpFunction.functionInfo.summary
+
+                    if (httpFunction.functionInfo?.description)
+                        path.description = httpFunction.functionInfo.description
+
+                    Object.assign(paths, {[`/${event.http.path}`]: path})
+                }
+            }
+        }
+        Object.assign(this.openAPI, {paths})
+    }
+
+    createOperationObject(method, documentation, name = uuid()) {
+        const obj = {
+            summary: documentation.summary || '',
+            description: documentation.description || '',
+            operationId: documentation.operationId || name,
+            parameters: [],
+            tags: documentation.tags || []
+        }
+
+        if (documentation.pathParams) {
+            const paramObject = this.createParamObject('path', documentation)
+            obj.parameters = obj.parameters.concat(paramObject)
+        }
+
+        if (documentation.queryParams) {
+            const paramObject = this.createParamObject('query', documentation)
+            obj.parameters = obj.parameters.concat(paramObject)
+        }
+
+        if (documentation.headerParams) {
+            const paramObject = this.createParamObject('header', documentation)
+            obj.parameters = obj.parameters.concat(paramObject)
+        }
+
+        if (documentation.cookieParams) {
+            const paramObject = this.createParamObject('cookie', documentation)
+            obj.parameters = obj.parameters.concat(paramObject)
+        }
+
+        if (Object.keys(documentation).includes('deprecated'))
+            obj[method].deprecated = documentation.deprecated
+
+        if (documentation.requestBody)
+            obj.requestBody = this.createRequestBody(documentation)
+
+        if (documentation.methodResponses)
+            obj.responses = this.createResponses(documentation)
+
+        return {[method]: obj}
+    }
+
+    createResponses(documentation) {
+        const responses = {}
+        for (const response of documentation.methodResponses) {
+            const obj = {
+                description: response.responseBody.description || '',
+            }
+
+            obj.content = this.createMediaTypeObject(response.responseModels, 'responses')
+
+            Object.assign(responses,{[response.statusCode]: obj})
+        }
+
+        return responses
+    }
+
+    createRequestBody(documentation) {
+        const obj = {
+            description: documentation.requestBody.description,
+            required: documentation.requestBody.required || false,
+        }
+
+        obj.content = this.createMediaTypeObject(documentation.requestModels, 'requestBody')
+
+        return obj
+    }
+
+    createMediaTypeObject(models, type) {
+        const mediaTypeObj = {}
+        for (const mediaTypeDocumentation of this.serverless.service.custom.documentation.models) {
+            if (Object.values(models).includes(mediaTypeDocumentation.name)) {
+                let contentKey = ''
+                for (const [key, value] of Object.entries(models)) {
+                    if (value === mediaTypeDocumentation.name)
+                        contentKey = key;
+                }
+                const obj = {}
+
+                if (mediaTypeDocumentation.example)
+                    obj.example = mediaTypeDocumentation.example
+
+                if (mediaTypeDocumentation.examples)
+                    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)
+                            }
+                        }
+                    }
+                }
+
+                Object.assign(mediaTypeObj, {[contentKey]: obj})
+            }
+        }
+        return mediaTypeObj
+    }
+
+    createParamObject(paramIn, documentation) {
+        const params = []
+        for (const param of documentation[`${paramIn}Params`]) {
+            const obj = {
+                name: param.name,
+                in: paramIn,
+                description: param.description || '',
+                required: (paramIn === 'path') ? true : param.required || false,
+            }
+
+            if (Object.keys(param).includes('deprecated')) {
+                obj.deprecated = param.deprecated
+            }
+
+            if (paramIn === 'query' && Object.keys(param).includes('allowEmptyValue')) {
+                obj.allowEmptyValue = param.allowEmptyValue
+            }
+
+            if (param.style)
+                obj.style = param.style
+
+            if (param.explode)
+                obj.explode = param.explode
+
+            if (paramIn === 'query' && param.allowReserved)
+                obj.allowReserved = param.allowReserved
+
+            if (param.example)
+                obj.example = param.example
+
+            if (param.examples)
+                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})
+
+                }
+            }
+
+            params.push(obj)
+        }
+        return params;
+    }
+
+    createExamples(examples) {
+        const examplesObj = {}
+
+        for(const example of examples) {
+            Object.assign(examplesObj, {[example.name]: example})
+        }
+
+        return examplesObj;
+    }
+
+    getHTTPFunctions() {
+        const isHttpFunction = (funcType) => {
+            const keys = Object.keys(funcType)
+            if (keys.includes(this.httpKeys.http) || keys.includes(this.httpKeys.httpAPI))
+                return true
+        }
+        const functionNames = this.serverless.service.getAllFunctions()
+
+        return functionNames.map(functionName => {
+            return this.serverless.service.getFunction(functionName)
+        })
+            .filter(functionType => {
+                if (functionType?.events.some(isHttpFunction))
+                    return functionType
+            })
+            .map(functionType => {
+                const event = functionType.events.filter(isHttpFunction)
+                return {
+                    functionInfo: functionType,
+                    handler: functionType.handler,
+                    name: functionType.name,
+                    event
+                }
+            })
+    }
+
+    async validate() {
+        return await validator.validateInner(this.openAPI, {})
+            .catch(err => {
+                throw err
+            })
+    }
+}
+
+module.exports = DefinitionGenerator

package/src/openAPIGenerator.js

@@ -0,0 +1,210 @@
+'use strict'
+
+const fs = require('fs')
+const yaml = require('js-yaml');
+const chalk = require('chalk')
+
+const DefinitionGenerator = require('./definitionGenerator')
+const PostmanGenerator = require('openapi-to-postmanv2')
+
+class OpenAPIGenerator {
+    constructor(serverless, options, {log = {}} = {}) {
+        this.logOutput = log;
+        this.serverless = serverless
+        this.options = options
+        this.defaultLog = 'notice';
+        this.commands = {
+          openapi: {
+            commands: {
+              generate: {
+                lifecycleEvents: [
+                  'serverless',
+                ],
+                usage: 'Generate OpenAPI v3 Documentation',
+                options: {
+                  output: {
+                    usage: 'Output file location [default: openapi.json|yml]',
+                    shortcut: 'o',
+                    type: 'string',
+                  },
+                  format: {
+                    usage: 'OpenAPI file format (yml|json) [default: json]',
+                    shortcut: 'f',
+                    type: 'string',
+                  },
+                  indent: {
+                    usage: 'File indentation in spaces [default: 2]',
+                    shortcut: 'i',
+                    type: 'string',
+                  },
+                  openApiVersion: {
+                    usage: 'OpenAPI version number [default 3.0.0]',
+                    shortcut: 'a',
+                    type: 'string'
+                  },
+                  postmanCollection: {
+                    usage: 'Output a postman collection and attach to openApi external documents [default: postman.json if passed]',
+                    shortcut: 'p',
+                    type: 'string'
+                  }
+                },
+              },
+            },
+          },
+        }
+
+        this.hooks = {
+          // 'before:deploy': this.beforeDeploy.bind(this),
+          'openapi:generate:serverless': this.generate.bind(this),
+        };
+
+        this.customVars = this.serverless.variables.service.custom;
+
+        this.serverless.configSchemaHandler.defineFunctionEventProperties('aws', 'http', {
+          properties: {
+            documentation: { type: 'object' },
+          },
+          required: ['documentation'],
+        });
+
+        this.serverless.configSchemaHandler.defineFunctionProperties('aws', {
+          properties: {
+            // description: {type: 'string'},
+            summary: {type: 'string'}
+          }
+        })
+    }
+
+    log(type = this.defaultLog, ...str) {
+        switch(this.serverless.version[0]) {
+          case '2':
+            this.serverless.cli.log(str)
+            break
+
+          case '3':
+            this.logOutput[type](str)
+            break
+
+          default:
+            process.stdout.write(str.join(' '))
+            break
+        }
+    }
+
+    async generate() {
+        this.log(this.defaultLog, chalk.bold.underline('OpenAPI v3 Document Generation'))
+        const config = this.processCliInput()
+        const generator = new DefinitionGenerator(this.serverless);
+
+        generator.parse();
+
+        const valid = await generator.validate()
+          .catch(err => {
+
+            this.log('error', chalk.bold.red(`ERROR: An error was thrown generation the OpenAPI v3 documentation`))
+            throw new this.serverless.classes.Error(err)
+          })
+
+        if (valid)
+          this.log(this.defaultLog, chalk.bold.green('OpenAPI v3 Documentation Successfully Generated'))
+
+        if (config.postmanCollection) {
+          const postmanGeneration = (err, result) => {
+            if (err) {
+              this.log('error', chalk.bold.red(`ERROR: An error was thrown when generating the postman collection`))
+              throw new this.serverless.classes.Error(err)
+            }
+
+            this.log(this.defaultLog, chalk.bold.green('postman collection v2 Documentation Successfully Generated'))
+            try {
+              fs.writeFileSync(config.postmanCollection, JSON.stringify(result.output[0].data))
+              this.log(this.defaultLog, chalk.bold.green('postman collection v2 Documentation Successfully Written'))
+            } catch (err) {
+              this.log('error', chalk.bold.red(`ERROR: An error was thrown whilst writing the postman collection`))
+              throw new this.serverless.classes.Error(err)
+            }
+          }
+
+          const postmanCollection = PostmanGenerator.convert(
+            {type: 'json', data: generator.openAPI},
+            {},
+            postmanGeneration
+          )
+        }
+
+        let output
+        switch (config.format.toLowerCase()) {
+          case 'json':
+            output = JSON.stringify(generator.openAPI, null, config.indent);
+            break;
+          case 'yaml':
+          default:
+            output = yaml.dump(generator.openAPI, { indent: config.indent });
+            break;
+        }
+        try {
+          fs.writeFileSync(config.file, output);
+          this.log(this.defaultLog, chalk.bold.green('OpenAPI v3 Documentation Successfully Written'))
+        } catch (err) {
+          this.log('error', chalk.bold.red(`ERROR: An error was thrown whilst writing the openAPI Documentation`))
+          throw new this.serverless.classes.Error(err)
+        }
+    }
+
+    processCliInput () {
+      const config = {
+        format: 'json',
+        file: 'openapi.json',
+        indent: 2,
+        openApiVersion: '3.0.0',
+        postmanCollection: 'postman.json'
+      };
+
+      config.indent = this.serverless.processedInput.options.indent || 2;
+      config.format = this.serverless.processedInput.options.format || 'json';
+      config.openApiVersion = this.serverless.processedInput.options.openApiVersion || '3.0.0';
+      config.postmanCollection = this.serverless.processedInput.options.postmanCollection || null
+
+      if (['yaml', 'json'].indexOf(config.format.toLowerCase()) < 0) {
+        throw new Error('Invalid Output Format Specified - must be one of "yaml" or "json"');
+      }
+
+      config.file = this.serverless.processedInput.options.output ||
+        ((config.format === 'yaml') ? 'openapi.yml' : 'openapi.json');
+
+      this.log(
+        this.defaultLog,
+        `${chalk.bold.green('[OPTIONS]')}`,
+        ` openApiVersion: "${chalk.bold.red(String(config.openApiVersion))}"`,
+        ` format: "${chalk.bold.red(config.format)}"`,
+        ` output file: "${chalk.bold.red(config.file)}"`,
+        ` indentation: "${chalk.bold.red(String(config.indent))}"`,
+        ` ${config.postmanCollection ? `postman collection: ${chalk.bold.red(config.postmanCollection)}`: `\n\n`}`
+      )
+
+      return config
+    }
+
+    validateDetails(validation) {
+      if (validation.valid) {
+        this.log(this.defaultLog, `${ chalk.bold.green('[VALIDATION]') } OpenAPI valid: ${chalk.bold.green('true')}\n\n`);
+      } else {
+        this.log(this.defaultLog, `${chalk.bold.red('[VALIDATION]')} Failed to validate OpenAPI document: \n\n`);
+        this.log(this.defaultLog, `${chalk.bold.green('Context:')} ${JSON.stringify(validation.context, null, 2)}\n`);
+        this.log(this.defaultLog, `${chalk.bold.green('Error Message:')} ${JSON.stringify(validation.error, null, 2)}\n`);
+        if (typeof validation.error === 'string') {
+          this.log(this.defaultLog, `${validation.error}\n\n`);
+        } else {
+          for (const info of validation.error) {
+            this.log(this.defaultLog, chalk.grey('\n\n--------\n\n'));
+            this.log(this.defaultLog, ' ', chalk.blue(info.dataPath), '\n');
+            this.log(this.defaultLog, ' ', info.schemaPath, chalk.bold.yellow(info.message));
+            this.log(this.defaultLog, chalk.grey('\n\n--------\n\n'));
+            this.log(this.defaultLog, `${inspect(info, { colors: true, depth: 2 })}\n\n`);
+          }
+        }
+      }
+    }
+}
+
+module.exports = OpenAPIGenerator

package/test/models/ErrorResponse.json

@@ -0,0 +1,118 @@
+{
+  "$schema": "http://json-schema.org/draft-04/schema#",
+  "title": "JSON API Schema",
+  "description": "This is a schema 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
+    },
+    "meta": {
+      "$ref": "#/definitions/meta"
+    },
+    "links": {
+      "$ref": "#/definitions/links"
+    }
+  },
+  "additionalProperties": false,
+  "definitions": {
+    "meta": {
+      "description": "Non-standard meta-information that can not be represented as an attribute or relationship.",
+      "type": "object",
+      "additionalProperties": true
+    },
+    "links": {
+      "description": "A resource object **MAY** contain references to other resource objects (\"relationships\"). Relationships may be to-one or to-many. Relationships can be specified by including a member in a resource's links object.",
+      "type": "object",
+      "properties": {
+        "self": {
+          "description": "A `self` member, whose value is a URL for the relationship itself (a \"relationship URL\"). This URL allows the client to directly manipulate the relationship. For example, it would allow a client to remove an `author` from an `article` without deleting the people resource itself.",
+          "type": "string",
+          "format": "uri"
+        },
+        "related": {
+          "$ref": "#/definitions/link"
+        }
+      },
+      "additionalProperties": true
+    },
+    "link": {
+      "description": "A link **MUST** be represented as either: a string containing the link's URL or a link object.",
+      "oneOf": [
+        {
+          "description": "A string containing the link's URL.",
+          "type": "string",
+          "format": "uri"
+        },
+        {
+          "type": "object",
+          "required": [
+            "href"
+          ],
+          "properties": {
+            "href": {
+              "description": "A string containing the link's URL.",
+              "type": "string",
+              "format": "uri"
+            },
+            "meta": {
+              "$ref": "#/definitions/meta"
+            }
+          }
+        }
+      ]
+    },
+    "error": {
+      "type": "object",
+      "properties": {
+        "id": {
+          "description": "A unique identifier for this particular occurrence of the problem.",
+          "type": "string"
+        },
+        "links": {
+          "$ref": "#/definitions/links"
+        },
+        "status": {
+          "description": "The HTTP status code applicable to this problem, expressed as a string value.",
+          "type": "string"
+        },
+        "code": {
+          "description": "An application-specific error code, expressed as a string value.",
+          "type": "string"
+        },
+        "title": {
+          "description": "A short, human-readable summary of the problem. It **SHOULD NOT** change from occurrence to occurrence of the problem, except for purposes of localization.",
+          "type": "string"
+        },
+        "detail": {
+          "description": "A human-readable explanation specific to this occurrence of the problem.",
+          "type": "string"
+        },
+        "source": {
+          "type": "object",
+          "properties": {
+            "pointer": {
+              "description": "A JSON Pointer [RFC6901] to the associated entity in the request document [e.g. \"/data\" for a primary data object, or \"/data/attributes/title\" for a specific attribute].",
+              "type": "string"
+            },
+            "parameter": {
+              "description": "A string indicating which query parameter caused the error.",
+              "type": "string"
+            }
+          }
+        },
+        "meta": {
+          "$ref": "#/definitions/meta"
+        }
+      },
+      "additionalProperties": false
+    }
+  }
+}

package/test/models/PutDocumentResponse.json

@@ -0,0 +1,5 @@
+{
+  "$schema": "http://json-schema.org/draft-04/schema#",
+  "title" : "Empty Schema",
+  "type" : "object"
+}