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

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.121",
   "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,7 +49,8 @@
   "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.15.0",
     "chalk": "^4.1.2",
     "js-yaml": "^4.1.1",
     "json-schema-for-openapi": "^0.5.0",

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/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();
@@ -163,30 +157,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'
-            }
-        }
-    }
-}

package/test/json/complex.json

@@ -1,91 +0,0 @@
-{
-    "$comment": "JSON Schema for CSR Framework",
-    "$schema": "http://json-schema.org/draft-04/schema",
-    "definitions": {
-      "log": {
-        "type": "object",
-        "title": "Logger options",
-        "properties": {
-          "channel": {
-            "type": "string",
-            "default": "console"
-          },
-          "path": {
-            "type": "string",
-            "default": "../src/logs"
-          },
-          "template": {
-            "type": "object",
-            "properties": {
-              "message": {
-                "type": "string"
-              },
-              "file": {
-                "type": "string"
-              },
-              "dir": {
-                "type": "string"
-              }
-            }
-          },
-          "telegram": {
-            "type": "object",
-            "properties": {
-              "bot_token": {
-                "type": "string"
-              },
-              "chat_id": {
-                "type": "string"
-              }
-            },
-            "required": ["chat_id", "bot_token"]
-          }
-        }
-      },
-      "template": {
-        "type": "object",
-        "properties": {
-          "path": {
-            "type": "string"
-          },
-          "cache": {
-            "type": "string"
-          }
-        }
-      },
-      "database": {
-        "type": "object",
-        "patternProperties": {
-          ".*": {
-            "type": "object",
-            "properties": {
-              "provider": {
-                "type": "string"
-              },
-              "user": {
-                "type": "string"
-              },
-              "password": {
-                "type": "string"
-              }
-            },
-            "required": ["provider"]
-          }
-        }
-      }
-    },
-    "id": "https://json.schemastore.org/csr",
-    "properties": {
-      "log": {
-        "$ref": "#/definitions/log"
-      },
-      "template": {
-        "$ref": "#/definitions/template"
-      },
-      "database": {
-        "$ref": "#/definitions/database"
-      }
-    },
-    "title": "CSR Framework schema",
-    "type": "object"
-  }

package/test/json/newOWASP.json

@@ -1,53 +0,0 @@
-{
-  "last_update_utc": "2024-09-19 21:29:28",
-  "headers": [
-    {
-      "name": "Cache-Control",
-      "value": "no-store, max-age=0"
-    },
-    {
-      "name": "Clear-Site-Data",
-      "value": "\"cache\",\"cookies\",\"storage\""
-    },
-    {
-      "name": "Content-Security-Policy",
-      "value": "default-src 'self'; form-action 'self'; object-src 'none'; frame-ancestors 'none'; upgrade-insecure-requests; block-all-mixed-content"
-    },
-    {
-      "name": "Cross-Origin-Embedder-Policy",
-      "value": "require-corp"
-    },
-    {
-      "name": "Cross-Origin-Opener-Policy",
-      "value": "same-origin"
-    },
-    {
-      "name": "Cross-Origin-Resource-Policy",
-      "value": "same-origin"
-    },
-    {
-      "name": "Permissions-Policy",
-      "value": "accelerometer=(), autoplay=(), camera=(), cross-origin-isolated=(), display-capture=(), encrypted-media=(), fullscreen=(), geolocation=(), gyroscope=(), keyboard-map=(), magnetometer=(), microphone=(), midi=(), payment=(), picture-in-picture=(), publickey-credentials-get=(), screen-wake-lock=(), sync-xhr=(self), usb=(), web-share=(), xr-spatial-tracking=(), clipboard-read=(), clipboard-write=(), gamepad=(), hid=(), idle-detection=(), interest-cohort=(), serial=(), unload=()"
-    },
-    {
-      "name": "Referrer-Policy",
-      "value": "no-referrer"
-    },
-    {
-      "name": "Strict-Transport-Security",
-      "value": "max-age=31536000; includeSubDomains"
-    },
-    {
-      "name": "X-Content-Type-Options",
-      "value": "nosniff"
-    },
-    {
-      "name": "X-Frame-Options",
-      "value": "deny"
-    },
-    {
-      "name": "X-Permitted-Cross-Domain-Policies",
-      "value": "none"
-    }
-  ]
-}