serverless-openapi-documenter 0.0.97 → 0.0.101

package/README.md

@@ -48,7 +48,7 @@ Options:
 --format                -f  Whether to output the OpenAPI Description as json or yaml. Default: json
 --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
+--postmanCollection     -p  Will generate a postman collection (from the generated OpenAPI Description), in json only, if passed in. Default: postman.json
 --validationWarn        -w  Warn about validation errors only.  Will write the OpenAPI file if generation is successful.  Default: false
 ```
 
@@ -942,16 +942,33 @@ This will set the `Cache-Control` Response Header to have a value of "no-store"
 
 Validation for the OpenAPI Description is now (as of 0.0.90) done by [Redocly](https://redocly.com/). This is a slightly less opinionated validator for an OpenAPI Description, it should result in less errors around "YAML Anchors". It's also a maintained library, and has support for OpenAPI 3.1.0 which I hope to be able to support very soon.
 
+I am making use of https://www.npmjs.com/package/@redocly/openapi-core, which I have been warned is likely to change. If you notice anything going wrong with validation of your OpenAPI Description, feel free to open an issue here. I make active use of this library, so will hopefully come across those issues too.
+
+### Rules
+
 I have configured the validator to use these Rules:
 
-* [spec](https://redocly.com/docs/cli/rules/spec/)
-* [path-parameters-defined](https://redocly.com/docs/cli/rules/path-parameters-defined/)
-* [operation-2xx-response](https://redocly.com/docs/cli/rules/operation-2xx-response/)
-* [operation-4xx-response](https://redocly.com/docs/cli/rules/operation-4xx-response/)
-* [operation-operationId-unique](https://redocly.com/docs/cli/rules/operation-operationid-unique/)
-* [path-declaration-must-exist](https://redocly.com/docs/cli/rules/path-declaration-must-exist/)
+- [spec](https://redocly.com/docs/cli/rules/spec/)
+- [path-parameters-defined](https://redocly.com/docs/cli/rules/path-parameters-defined/)
+- [operation-2xx-response](https://redocly.com/docs/cli/rules/operation-2xx-response/)
+- [operation-4xx-response](https://redocly.com/docs/cli/rules/operation-4xx-response/)
+- [operation-operationId-unique](https://redocly.com/docs/cli/rules/operation-operationid-unique/)
+- [path-declaration-must-exist](https://redocly.com/docs/cli/rules/path-declaration-must-exist/)
 
-I am making use of https://www.npmjs.com/package/@redocly/openapi-core, which I have been warned is likely to change. If you notice anything going wrong with validation of your OpenAPI Description, feel free to open an issue here. I make active use of this library, so will hopefully come across those issues too.
+However, you can configure your own rules from the [ruleset available on the Redocly site](https://redocly.com/docs/cli/rules/built-in-rules/). To do this, you will need to create a `redocly.json` file within an `options` folder. The file should look like:
+
+```json
+{
+  "spec": "error",
+  "path-parameters-defined": "error",
+  "operation-2xx-response": "error",
+  "operation-4xx-response": "error",
+  "operation-operationId-unique": "error",
+  "path-declaration-must-exist": "error"
+}
+```
+
+Since rules can be set to "warn", you no longer are required to tell the plugin to ignore errors with the `--validationWarn` flag.
 
 ## Example configuration
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "serverless-openapi-documenter",
-  "version": "0.0.97",
+  "version": "0.0.101",
   "description": "Generate OpenAPI v3 documentation and Postman Collections from your Serverless Config",
   "main": "index.js",
   "keywords": [

package/src/definitionGenerator.js

@@ -69,6 +69,19 @@ class DefinitionGenerator {
       },
     };
 
+    try {
+      this.REDOCLY_RULES = require(path.resolve("options", "redocly.json"));
+    } catch (err) {
+      this.REDOCLY_RULES = {
+        spec: "error",
+        "path-parameters-defined": "error",
+        "operation-2xx-response": "error",
+        "operation-4xx-response": "error",
+        "operation-operationId-unique": "error",
+        "path-declaration-must-exist": "error",
+      };
+    }
+
     try {
       this.refParserOptions = require(path.resolve("options", "ref-parser.js"));
     } catch (err) {
@@ -1003,33 +1016,18 @@ class DefinitionGenerator {
   async validate() {
     const config = await createConfig({
       apis: {},
-      // styleguide: {
-      rules: {
-        spec: "error",
-        "path-parameters-defined": "error",
-        "operation-2xx-response": "error",
-        "operation-4xx-response": "error",
-        "operation-operationId-unique": "error",
-        "path-declaration-must-exist": "error",
-      },
-      // },
+      rules: this.REDOCLY_RULES,
     });
 
     const apiDesc = stringifyYaml(this.openAPI);
 
-    const results = await lintFromString({
+    return await lintFromString({
       source: apiDesc,
       config: config,
     }).catch((err) => {
       console.error(err);
       throw err;
     });
-
-    if (results.length) {
-      throw results;
-    }
-
-    return true;
   }
 }
 

package/src/openAPIGenerator.js

@@ -195,23 +195,29 @@ class OpenAPIGenerator {
 
     this.log(`Validating generated OpenAPI Description`, this.logTypes.NOTICE);
 
-    await generator.validate().catch((err) => {
+    const validationResults = await generator.validate().catch((err) => {
       this.log(
         `ERROR: An error was thrown validating the OpenAPI v3 Description`,
         this.logTypes.ERROR
       );
 
-      this.validationErrorDetails(err);
+      throw new this.serverless.classes.Error(err);
+    });
 
-      if (this.config.validationWarn === false) {
-        let message = "Error validating OpenAPI Description:\r\n";
-        for (const errorMessage of err) {
-          message += `${errorMessage.message}\r\n`;
-        }
+    this.validationErrorDetails(validationResults);
 
-        throw new this.serverless.classes.Error(message);
+    if (validationResults.length && this.config.validationWarn === false) {
+      let message = "Error validating OpenAPI Description:\r\n";
+      let shouldThrow = false;
+      for (const error of validationResults) {
+        message += `${error.message}\r\n`;
+        if (error.severity === "error") {
+          shouldThrow = true;
+        }
       }
-    });
+
+      if (shouldThrow) throw new this.serverless.classes.Error(message);
+    }
 
     this.log(
       "OpenAPI v3 Description Successfully Generated",
@@ -306,24 +312,30 @@ class OpenAPIGenerator {
     this.config = config;
   }
 
-  validationErrorDetails(validationError) {
-    this.log(
-      `${chalk.bold.yellow(
-        "[VALIDATION]"
-      )} Validation errors found in OpenAPI Description: \n`,
-      this.logTypes.ERROR
-    );
-
-    for (const error of validationError) {
+  validationErrorDetails(validationErrors) {
+    if (validationErrors.length) {
       this.log(
-        `${chalk.bold.yellow("Message:")} ${error.message}`,
+        `${chalk.bold.yellow(
+          "[VALIDATION]"
+        )} Validation errors found in OpenAPI Description: \n`,
         this.logTypes.ERROR
       );
-      for (const location of error.location) {
+
+      for (const error of validationErrors) {
         this.log(
-          `${chalk.bold.yellow("found at location:")} ${location.pointer}`,
+          `${chalk.bold.red("Severity:")} ${error.severity}`,
           this.logTypes.ERROR
         );
+        this.log(
+          `${chalk.bold.yellow("Message:")} ${error.message}`,
+          this.logTypes.ERROR
+        );
+        for (const location of error.location) {
+          this.log(
+            `${chalk.bold.yellow("found at location:")} ${location.pointer}`,
+            this.logTypes.ERROR
+          );
+        }
       }
     }
   }

package/test/helpers/redocly.json

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