serverless-openapi-documenter 0.0.120-beta.1 → 0.0.123

package/README.md

@@ -12,9 +12,7 @@
   </a>
 </p>
 
-This will generate an [OpenAPI V3](https://spec.openapis.org/oas/v3.0.0.html) (up to v3.0.4) specification 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. This currently works for `http` and `httpApi` configurations.
-
-If you are using the beta of 0.0.115, it will now try and create [OpenAPI V3.1 (3.1.x)](https://spec.openapis.org/oas/v3.1.0.html) specification file for you, should you run the command `serverless openapi generate -o openapi.json -f json -a 3.1.1 -p postman.json`. Please see this [guide on migrating to V3.1](https://www.openapis.org/blog/2021/02/16/migrating-from-openapi-3-0-to-3-1-0). Whilst I perosnally use this plugin all the time, please do open and report bugs, and I will do my best to fix them.
+This will generate an OpenAPI V3 (up to v3.0.4) file for you from your serverless file. It can optionally generate a [Postman Collection V2](https://github.com/postmanlabs/openapi-to-postman) or (as of 0.0.120) [Bruno Collection](https://docs.usebruno.com/) from the OpenAPI file. This currently works for `http` and `httpApi` configurations.
 
 Originally based off of: https://github.com/temando/serverless-openapi-documentation
 
@@ -51,6 +49,7 @@ Options:
 --indent                -i  File indentation in spaces. Default: 2
 --openApiVersion        -a  OpenAPI version to generate for. Default: 3.0.0
 --postmanCollection     -p  Will generate a postman collection (from the generated OpenAPI Description), in json only, if passed in. Default: postman.json
+--brunoCollection       -b  Will generate a Bruno collection (from the generated OpenAPI Description), in json only, if passed in. Default: bruno.json
 --validationWarn        -w  Warn about validation errors only.  Will write the OpenAPI file if generation is successful.  Default: false
 ```
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "serverless-openapi-documenter",
-  "version": "0.0.120-beta.1",
+  "version": "0.0.123",
   "description": "Generate OpenAPI v3 documentation and Postman Collections from your Serverless Config",
   "main": "index.js",
   "keywords": [
@@ -22,6 +22,9 @@
     "PostmanCollections",
     "Postman-Collections",
     "Postman Collections",
+    "Bruno Collection",
+    "Bruno",
+    "Use Bruno",
     "AWS",
     "AWS APIGateway",
     "Api Gateway",
@@ -46,11 +49,12 @@
   "license": "MIT",
   "dependencies": {
     "@apidevtools/json-schema-ref-parser": "^9.1.0",
-    "@redocly/openapi-core": "^1.34.5",
+    "@redocly/openapi-core": "^1.2.0",
+    "@usebruno/converters": "^0.16.0",
     "chalk": "^4.1.2",
     "js-yaml": "^4.1.1",
     "json-schema-for-openapi": "^0.5.0",
-    "openapi-to-postmanv2": "^5.6.0",
+    "openapi-to-postmanv2": "^6.0.0",
     "uuid": "^11.1.0"
   },
   "engines": {

package/src/bruno.js

@@ -0,0 +1,32 @@
+'use strict';
+
+const { openApiToBruno } = require('@usebruno/converters');
+
+const fs = require('fs/promises')
+
+class Bruno {
+    constructor(output, serverless, logger) {
+        this.output = output;
+        this.logger = logger;
+        this.serverless = serverless;
+    }
+
+    async create(openAPI) {
+        try {
+            const brunoCollection = openApiToBruno(openAPI);
+
+            await fs.writeFile(this.output, JSON.stringify(brunoCollection, null, 2));
+            this.logger.success(
+                "Bruno collection Documentation Successfully Written"
+            );
+        } catch (error) {
+            this.logger.error(
+                `ERROR: An error was thrown whilst writing the Bruno collection`
+            );
+
+            throw new this.serverless.classes.Error(error);
+        }
+    }
+}
+
+module.exports = Bruno;

package/src/collection.js

@@ -0,0 +1,29 @@
+'use strict';
+
+const Bruno = require('./bruno');
+const Postman = require('./postman');
+
+class CollectionFactory {
+    constructor(outputFile, serverless, logger) {
+        this.outputFile = outputFile;
+        this.serverless = serverless;
+        this.logger = logger;
+    }
+
+    createCollection(type) {
+        let creator;
+        switch (type){
+            case 'bruno':
+                creator = new Bruno(this.outputFile, this.serverless, this.logger);
+            break;
+
+            case 'postman':
+                creator = new Postman(this.outputFile, this.serverless, this.logger);
+            break;
+        }
+
+        return creator;
+    }
+}
+
+module.exports = CollectionFactory;

package/src/definitionGenerator.js

@@ -167,11 +167,12 @@ class DefinitionGenerator {
 
     if (documentation.contact) {
       const contactObj = {};
-      contactObj.name = documentation.contact.name || "";
+
+      if (documentation.contact.name) contactObj.name = documentation.contact.name;
 
       if (documentation.contact.url) contactObj.url = documentation.contact.url;
 
-      contactObj.email = documentation.contact.email || "";
+      if (documentation.contact.email) contactObj.email = documentation.contact.email;
 
       const extendedSpec = this.extendSpecification(documentation.contact);
 
@@ -591,7 +592,9 @@ class DefinitionGenerator {
           obj.headers = corsHeaders;
           addHeaders(owaspHeaders);
         } else {
-          obj.headers = owaspHeaders;
+          if (Object.keys(owaspHeaders).length) {
+            obj.headers = owaspHeaders;
+          }
         }
       }
 
@@ -677,10 +680,13 @@ class DefinitionGenerator {
 
   async createRequestBody(requestBodyDetails) {
     const obj = {
-      description: requestBodyDetails.description,
       required: requestBodyDetails.required || false,
     };
 
+    if (requestBodyDetails.description) {
+      obj.description = requestBodyDetails.description;
+    }
+
     obj.content = await this.createMediaTypeObject(
       requestBodyDetails.models
     ).catch((err) => {
@@ -692,7 +698,6 @@ class DefinitionGenerator {
 
   async createMediaTypeObject(models, type) {
     const mediaTypeObj = {};
-
     for (const mediaTypeDocumentation of this.schemaHandler.models) {
       if (models === undefined || models === null) {
         throw new Error(
@@ -700,48 +705,53 @@ class DefinitionGenerator {
         );
       }
 
-      if (Object.values(models).includes(mediaTypeDocumentation.name)) {
-        let contentKey = "";
-        for (const [key, value] of Object.entries(models)) {
-          if (value === mediaTypeDocumentation.name) contentKey = key;
+      for (const modelContentType in models) {
+        let contentKey
+
+        if (models[modelContentType] === mediaTypeDocumentation.name) {
+          contentKey = modelContentType;
         }
-        const obj = {};
 
-        let schema;
-        if (mediaTypeDocumentation?.content) {
-          if (mediaTypeDocumentation.content[contentKey]?.example)
-            obj.example = mediaTypeDocumentation.content[contentKey].example;
+        if (contentKey) {
 
-          if (mediaTypeDocumentation.content[contentKey]?.examples)
-            obj.examples = this.createExamples(
-              mediaTypeDocumentation.content[contentKey].examples
-            );
+          const obj = {};
+          let schema;
+          if (mediaTypeDocumentation.content) {
+            if (mediaTypeDocumentation.content[contentKey]?.example) {
+              obj.example = mediaTypeDocumentation.content[contentKey]?.example;
+            }
 
-          schema = mediaTypeDocumentation.content[contentKey].schema;
-        } else if (
-          mediaTypeDocumentation?.contentType &&
-          mediaTypeDocumentation.schema
-        ) {
-          if (mediaTypeDocumentation?.example)
-            obj.example = mediaTypeDocumentation.example;
+            if (mediaTypeDocumentation.content[contentKey]?.examples) {
+              obj.examples = this.createExamples(
+                mediaTypeDocumentation.content[contentKey].examples
+              );
+            }
 
-          if (mediaTypeDocumentation?.examples)
-            obj.examples = this.createExamples(mediaTypeDocumentation.examples);
+            schema = (mediaTypeDocumentation.schema) ? mediaTypeDocumentation.schema : mediaTypeDocumentation.schemas[contentKey];
+          } else if (mediaTypeDocumentation?.contentType && mediaTypeDocumentation.schema) {
+            if (mediaTypeDocumentation.example) {
+              obj.example = mediaTypeDocumentation.example;
+            }
 
-          schema = mediaTypeDocumentation.schema;
-        }
+            if (mediaTypeDocumentation.examples) {
+              obj.example = mediaTypeDocumentation.examples;
+            }
 
-        const schemaRef = await this.schemaHandler
-          .createSchema(mediaTypeDocumentation.name)
-          .catch((err) => {
-            throw err;
-          });
+            schema = mediaTypeDocumentation.schema;
+          }
 
-        obj.schema = {
-          $ref: schemaRef,
-        };
+          const schemaRef = await this.schemaHandler
+            .createSchema(mediaTypeDocumentation.name)
+            .catch((err) => {
+              throw err;
+            });
 
-        Object.assign(mediaTypeObj, { [contentKey]: obj });
+          obj.schema = {
+            $ref: schemaRef,
+          };
+
+          Object.assign(mediaTypeObj, { [contentKey]: obj });
+        }
       }
     }
 
@@ -861,7 +871,7 @@ class DefinitionGenerator {
         if (
           this.openAPI.components[type][name] &&
           isEqual(schemaObj[name], this.openAPI.components[type][name]) ===
-            false
+          false
         ) {
           delete schemaObj[name];
           newName = `${name}-${uuid()}`;

package/src/openAPIGenerator.js

@@ -4,9 +4,9 @@ const fs = require("fs");
 const yaml = require("js-yaml");
 const chalk = require("chalk");
 
+const Collection = require('./collection')
 const DefinitionGenerator = require("./definitionGenerator");
 const Logger = require("./logger");
-const PostmanGenerator = require("openapi-to-postmanv2");
 
 class OpenAPIGenerator {
   constructor(serverless, options, { log = {} } = {}) {
@@ -44,10 +44,16 @@ class OpenAPIGenerator {
               },
               postmanCollection: {
                 usage:
-                  "Output a postman collection and attach to OpenApi external documents [default: postman.json if passed]",
+                  "Output a Postman collection and attach to OpenApi external documents [default: postman.json if passed]",
                 shortcut: "p",
                 type: "string",
               },
+              brunoCollection: {
+                usage:
+                  "Output a Bruno collection and attach to OpenApi external documents [default: bruno.json if passed]",
+                shortcut: "b",
+                type: "string",
+              },
               validationWarn: {
                 usage:
                   "Only warn about validation errors of the OpenAPI Description, write the file if parsing is successful [default: false]",
@@ -144,8 +150,9 @@ class OpenAPIGenerator {
       throw new this.serverless.classes.Error(err);
     });
 
-    if (this.config.postmanCollection) {
-      this.createPostman(validOpenAPI);
+    if (this.shouldCreateCollection()) {
+      await this.createCollection(validOpenAPI)
+
     }
 
     let output;
@@ -210,41 +217,21 @@ class OpenAPIGenerator {
     return generator.openAPI;
   }
 
-  createPostman(openAPI) {
-    const postmanGeneration = (err, result) => {
-      if (err) {
-        this.logger.error(
-          `ERROR: An error was thrown when generating the postman collection`
-        );
-        throw new this.serverless.classes.Error(err);
-      }
+  async createCollection(validOpenAPI) {
+    const collectionOutputFile = this.config.postmanCollection || this.config.brunoCollection
+    const collection = new Collection(collectionOutputFile, this.serverless, this.logger)
+    const collectionCreator = collection.createCollection(this.collectionType())
 
-      this.logger.success(
-        "postman collection v2 Documentation Successfully Generated"
-      );
+    await collectionCreator.create(validOpenAPI)
+  }
 
-      try {
-        fs.writeFileSync(
-          this.config.postmanCollection,
-          JSON.stringify(result.output[0].data)
-        );
-        this.logger.success(
-          "postman collection v2 Documentation Successfully Written"
-        );
-      } catch (err) {
-        this.logger.error(
-          `ERROR: An error was thrown whilst writing the postman collection`
-        );
-
-        throw new this.serverless.classes.Error(err);
-      }
-    };
+  shouldCreateCollection() {
+    return Boolean(this.config.postmanCollection || this.config.brunoCollection)
+  }
 
-    PostmanGenerator.convert(
-      { type: "json", data: structuredClone(openAPI) },
-      {},
-      postmanGeneration
-    );
+  collectionType() {
+    if (this.config.postmanCollection) return 'postman'
+    else return 'bruno'
   }
 
   processCliInput() {
@@ -254,6 +241,7 @@ class OpenAPIGenerator {
       indent: 2,
       openApiVersion: "3.0.0",
       postmanCollection: "postman.json",
+      brunoCollection: "bruno.json",
       validationWarn: false,
     };
 
@@ -263,6 +251,8 @@ class OpenAPIGenerator {
       this.serverless.processedInput.options.openApiVersion || "3.0.0";
     config.postmanCollection =
       this.serverless.processedInput.options.postmanCollection || null;
+    config.brunoCollection =
+      this.serverless.processedInput.options.brunoCollection || null;
     config.validationWarn =
       this.serverless.processedInput.options.validationWarn || false;
 
@@ -285,7 +275,12 @@ class OpenAPIGenerator {
   validationWarn: ${chalk.bold.green(String(config.validationWarn))}
   ${
     config.postmanCollection
-      ? `postman collection: ${chalk.bold.green(config.postmanCollection)}`
+      ? `Postman collection: ${chalk.bold.green(config.postmanCollection)}`
+      : `\n\n`
+  }
+  ${
+    config.brunoCollection
+      ? `Bruno collection: ${chalk.bold.green(config.brunoCollection)}`
       : `\n\n`
   }`
     );

package/src/postman.js

@@ -0,0 +1,53 @@
+'use strict';
+
+const PostmanGenerator = require("openapi-to-postmanv2");
+
+const fs = require('fs');
+
+class Postman {
+    constructor(output, serverless, logger) {
+        this.output = output;
+        this.logger = logger;
+        this.serverless = serverless;
+    }
+
+    create(openAPI) {
+        const postmanGeneration = (err, result) => {
+            if (err) {
+                this.logger.error(
+                    `ERROR: An error was thrown when generating the Postman collection`
+                );
+                throw new this.serverless.classes.Error(err);
+            }
+
+            this.logger.success(
+                "Postman collection v2 Documentation Successfully Generated"
+            );
+
+            try {
+                fs.writeFileSync(
+                    this.output,
+                    JSON.stringify(result.output[0].data)
+                );
+
+                this.logger.success(
+                    "Postman collection v2 Documentation Successfully Written"
+                );
+            } catch (err) {
+                this.logger.error(
+                    `ERROR: An error was thrown whilst writing the Postman collection`
+                );
+
+                throw new this.serverless.classes.Error(err);
+            }
+        };
+
+        PostmanGenerator.convert(
+            { type: "json", data: structuredClone(openAPI) },
+            {},
+            postmanGeneration
+        );
+    }
+}
+
+module.exports = Postman;

package/src/schemaHandler.js

@@ -16,12 +16,6 @@ class SchemaHandler {
     this.documentation = serverless.service.custom.documentation;
     this.openAPI = openAPI;
 
-    this.shouldConvert = true;
-    if (/(3\.1\.\d)/g.test(this.openAPI.openapi)) this.shouldConvert = false;
-
-    this.logger.verbose(`OpenAPI version: ${this.openAPI.openapi}`);
-    this.logger.verbose(`Convert Schemas: ${this.shouldConvert}`);
-
     this.modelReferences = {};
 
     this.__standardiseModels();
@@ -48,9 +42,21 @@ class SchemaHandler {
         return model;
       }
 
-      const contentType = Object.keys(model.content)[0];
-      model.contentType = contentType;
-      model.schema = model.content[contentType].schema;
+      if (Object.keys(model.content).length === 1) {
+        const contentType = Object.keys(model.content)[0];
+        model.contentType = contentType;
+        model.contentTypes = [contentType];
+        model.schema = model.content[contentType].schema;
+      } else {
+        model.contentType = null;
+        model.contentTypes = Object.keys(model.content);
+        model.schema = null;
+        model.schemas = {};
+        for (const key in model.content) {
+          Object.assign(model.schemas, {[key]: {schema: model.content[key].schema}});
+        }
+        // model.schema = model.content[contentType].schema;
+      }
 
       return model;
     };
@@ -75,43 +81,53 @@ class SchemaHandler {
   async addModelsToOpenAPI() {
     for (const model of this.models) {
       const modelName = model.name;
-      const modelSchema = model.schema;
+      const schemas = []
+      if (model.schema){
+        // const modelSchema = model.schema;
+        schemas.push(model.schema)
+      } else {
+        for (const key in model.schemas) {
+          schemas.push(model.schemas[key].schema);
+        }
+      }
 
-      const convertedSchemas = await this.__dereferenceAndConvert(
-        modelSchema,
-        modelName,
-        model
-      ).catch((err) => {
-        if (err instanceof Error) throw err;
-        else return err;
-      });
+      for (const modelSchema of schemas) {
+        const convertedSchemas = await this.__dereferenceAndConvert(
+          modelSchema,
+          modelName,
+          model
+        ).catch((err) => {
+          if (err instanceof Error) throw err;
+          else return err;
+        });
+
+        if (
+          typeof convertedSchemas.schemas === "object" &&
+          !Array.isArray(convertedSchemas.schemas) &&
+          convertedSchemas.schemas !== null
+        ) {
+          for (const [schemaName, schemaValue] of Object.entries(
+            convertedSchemas.schemas
+          )) {
+            if (schemaName === modelName) {
+              this.modelReferences[
+                schemaName
+              ] = `#/components/schemas/${modelName}`;
+            }
 
-      if (
-        typeof convertedSchemas.schemas === "object" &&
-        !Array.isArray(convertedSchemas.schemas) &&
-        convertedSchemas.schemas !== null
-      ) {
-        for (const [schemaName, schemaValue] of Object.entries(
-          convertedSchemas.schemas
-        )) {
-          if (schemaName === modelName) {
-            this.modelReferences[
-              schemaName
-            ] = `#/components/schemas/${modelName}`;
+            this.__addToComponents("schemas", schemaValue, schemaName);
           }
-
-          this.__addToComponents("schemas", schemaValue, schemaName);
+        } else {
+          throw new Error(
+            `There was an error converting the ${
+              model.name
+            } schema. Model received looks like: \n\n${JSON.stringify(
+              model
+            )}.  The convereted schema looks like \n\n${JSON.stringify(
+              convertedSchemas
+            )}`
+          );
         }
-      } else {
-        throw new Error(
-          `There was an error converting the ${
-            model.name
-          } schema. Model received looks like: \n\n${JSON.stringify(
-            model
-          )}.  The convereted schema looks like \n\n${JSON.stringify(
-            convertedSchemas
-          )}`
-        );
       }
     }
   }
@@ -163,30 +179,18 @@ class SchemaHandler {
       }
     );
 
-    if (this.shouldConvert) {
-      this.logger.verbose(
-        `dereferenced model: ${JSON.stringify(dereferencedSchema)}`
-      );
-
-      this.logger.verbose(`converting model: ${name}`);
-      const convertedSchemas = SchemaConvertor.convert(
-        dereferencedSchema,
-        name
-      );
+    this.logger.verbose(
+      `dereferenced model: ${JSON.stringify(dereferencedSchema)}`
+    );
 
-      this.logger.verbose(
-        `converted schemas: ${JSON.stringify(convertedSchemas)}`
-      );
-      return convertedSchemas;
-    }
+    this.logger.verbose(`converting model: ${name}`);
+    const convertedSchemas = SchemaConvertor.convert(dereferencedSchema, name);
 
     this.logger.verbose(
-      `dereferenced model: ${JSON.stringify({
-        schemas: { [name]: dereferencedSchema },
-      })}`
+      `converted schemas: ${JSON.stringify(convertedSchemas)}`
     );
 
-    return { schemas: { [name]: dereferencedSchema } };
+    return convertedSchemas;
   }
 
   async __dereferenceSchema(schema) {

package/test/.mocharc.js

@@ -1,9 +0,0 @@
-'use strict'
-
-module.exports = {
-    recursive: true,
-    reporter: 'spec',
-    spec: 'test/unit/*.spec.js',
-    watch: false,
-    'watch-files': ['src/**/*.js', 'test/**/*.spec.js'],
-}

package/test/helpers/redocly.json

@@ -1,4 +0,0 @@
-{
-  "struct": "error",
-  "operation-2xx-response": "warn"
-}

package/test/helpers/ref-parser.js

@@ -1,5 +0,0 @@
-'use strict'
-
-module.exports = {
-    continueOnError: true,            // Don't throw on the first error
-}

package/test/helpers/serverless.js

@@ -1,19 +0,0 @@
-'use strict'
-
-module.exports = {
-    processedInput: {
-        options: {
-            openApiVersion: '3.0.1'
-        }
-    },
-    service: {
-        service: 'myAPI',
-        custom: {
-            documentation: {
-                title: 'My new API',
-                description: 'This API does things',
-                version: '0.0.1'
-            }
-        }
-    }
-}