serverless-openapi-documenter 0.0.83 → 0.0.90

package/README.md

@@ -44,11 +44,11 @@ To Run: `serverless openapi generate -o openapi.json -f json -a 3.0.3 -p postman
 Options:
 
 ```
---output                -o  What filename the OpenAPI documentation should output under. Default: openapi.json
---format                -f  Whether to output the OpenAPI documentation as json or yaml. Default: json
+--output                -o  What filename the OpenAPI Description should output under. Default: openapi.json
+--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 documentation), 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
 ```
 
@@ -71,6 +71,10 @@ Options:
 - [CORS](#cors)
 - [OWASP Secure Headers](#owasp)
 
+#### Validation
+
+- [Validation](#validator)
+
 ### OpenAPI Mapping
 
 | OpenAPI field                                             | Serverless field                                                                                                                                      |
@@ -133,7 +137,7 @@ Options:
 
 ### Configuration
 
-To configure this plugin to generate valid OpenAPI documentation there are two places you'll need to modify in your `serverless.yml` file, the `custom` variables section and the `http/httpApi` event section for each given function in your service.
+To configure this plugin to generate a valid OpenAPI Description, there are two places you'll need to modify in your `serverless.yml` file, the `custom` variables section and the `http/httpApi` event section for each given function in your service.
 
 The `custom` section of your `serverless.yml` can be configured as below:
 
@@ -934,6 +938,12 @@ methodResponse:
 
 This will set the `Cache-Control` Response Header to have a value of "no-store" rather than any value the OWASP Secure Headers Project recommends.
 
+## Validator
+
+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.
+
 ## Example configuration
 
 Please view the example [serverless.yml](test/serverless-tests/best/serverless.yml).
@@ -975,7 +985,7 @@ We use the plugin [JSON Schema $Ref Parser](https://apitools.dev/json-schema-ref
 }
 ```
 
-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.
+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 Description.
 
 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.
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "serverless-openapi-documenter",
-  "version": "0.0.83",
+  "version": "0.0.90",
   "description": "Generate OpenAPI v3 documentation and Postman Collections from your Serverless Config",
   "main": "index.js",
   "keywords": [
@@ -38,12 +38,12 @@
   "license": "MIT",
   "dependencies": {
     "@apidevtools/json-schema-ref-parser": "^9.1.0",
+    "@redocly/openapi-core": "^1.2.0",
     "chalk": "^4.1.2",
     "js-yaml": "^4.1.0",
     "json-schema-for-openapi": "^0.4.1",
     "lodash.isequal": "^4.5.0",
-    "oas-validator": "^5.0.8",
-    "openapi-to-postmanv2": "^4.17.0",
+    "openapi-to-postmanv2": "^4.18.0",
     "swagger2openapi": "^7.0.8",
     "uuid": "^9.0.0"
   },

package/src/definitionGenerator.js

@@ -2,8 +2,13 @@
 
 const path = require("path");
 
+const {
+  Config,
+  lintFromString,
+  stringifyYaml,
+  createConfig,
+} = require("@redocly/openapi-core");
 const isEqual = require("lodash.isequal");
-const validator = require("oas-validator");
 const { v4: uuid } = require("uuid");
 
 const SchemaHandler = require("./schemaHandler");
@@ -971,9 +976,35 @@ class DefinitionGenerator {
   }
 
   async validate() {
-    return await validator.validateInner(this.openAPI, {}).catch((err) => {
+    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",
+      },
+      // },
+    });
+
+    const apiDesc = stringifyYaml(this.openAPI);
+
+    const results = await lintFromString({
+      source: apiDesc,
+      config: config,
+    }).catch((err) => {
+      console.error(err);
       throw err;
     });
+
+    if (results.length) {
+      throw results;
+    }
+
+    return true;
   }
 }
 

package/src/openAPIGenerator.js

@@ -30,7 +30,7 @@ class OpenAPIGenerator {
         commands: {
           generate: {
             lifecycleEvents: ["serverless"],
-            usage: "Generate OpenAPI v3 Documentation",
+            usage: "Generate OpenAPI v3 Description",
             options: {
               output: {
                 usage: "Output file location [default: openapi.json|yml]",
@@ -60,7 +60,7 @@ class OpenAPIGenerator {
               },
               validationWarn: {
                 usage:
-                  "Only warn about validation errors of the OpenAPI document, write the file if parsing is successful [default: false]",
+                  "Only warn about validation errors of the OpenAPI Description, write the file if parsing is successful [default: false]",
                 shortcut: "w",
                 type: "boolean",
               },
@@ -144,7 +144,7 @@ class OpenAPIGenerator {
   }
 
   async generate() {
-    this.log(chalk.bold.underline("OpenAPI v3 Document Generation"));
+    this.log(chalk.bold.underline("OpenAPI v3 Description Generation"));
     this.processCliInput();
 
     const validOpenAPI = await this.generationAndValidation().catch((err) => {
@@ -168,12 +168,12 @@ class OpenAPIGenerator {
     try {
       fs.writeFileSync(this.config.file, output);
       this.log(
-        "OpenAPI v3 Documentation Successfully Written",
+        "OpenAPI v3 Description Successfully Written",
         this.logTypes.SUCCESS
       );
     } catch (err) {
       this.log(
-        `ERROR: An error was thrown whilst writing the openAPI Documentation`,
+        `ERROR: An error was thrown whilst writing the OpenAPI Description`,
         this.logTypes.ERROR
       );
       throw new this.serverless.classes.Error(err);
@@ -183,33 +183,37 @@ class OpenAPIGenerator {
   async generationAndValidation() {
     const generator = new DefinitionGenerator(this.serverless);
 
-    this.log(`Generating OpenAPI documentation`, this.logTypes.NOTICE);
+    this.log(`Generating OpenAPI Description`, this.logTypes.NOTICE);
     await generator.parse().catch((err) => {
       this.log(
-        `ERROR: An error was thrown generating the OpenAPI v3 documentation`,
+        `ERROR: An error was thrown generating the OpenAPI v3 Description`,
         this.logTypes.ERROR
       );
       throw new this.serverless.classes.Error(err);
     });
 
-    this.log(
-      `Validating generated OpenAPI documentation`,
-      this.logTypes.NOTICE
-    );
+    this.log(`Validating generated OpenAPI Description`, this.logTypes.NOTICE);
 
     await generator.validate().catch((err) => {
       this.log(
-        `ERROR: An error was thrown validating the OpenAPI v3 documentation`,
+        `ERROR: An error was thrown validating the OpenAPI v3 Description`,
         this.logTypes.ERROR
       );
+
       this.validationErrorDetails(err);
+
       if (this.config.validationWarn === false) {
-        throw new this.serverless.classes.Error(err);
+        let message = "Error validating OpenAPI Description:\r\n";
+        for (const errorMessage of err) {
+          message += `${errorMessage.message}\r\n`;
+        }
+
+        throw new this.serverless.classes.Error(message);
       }
     });
 
     this.log(
-      "OpenAPI v3 Documentation Successfully Generated",
+      "OpenAPI v3 Description Successfully Generated",
       this.logTypes.SUCCESS
     );
 
@@ -305,27 +309,22 @@ class OpenAPIGenerator {
     this.log(
       `${chalk.bold.yellow(
         "[VALIDATION]"
-      )} Failed to validate OpenAPI document: \n`,
-      this.logTypes.ERROR
-    );
-    this.log(
-      `${chalk.bold.yellow("Context:")} ${JSON.stringify(
-        validationError.options.context[
-          validationError.options.context.length - 1
-        ],
-        null,
-        2
-      )}\n`,
-      this.logTypes.ERROR
-    );
-    this.log(
-      `${chalk.bold.yellow("Error Message:")} ${JSON.stringify(
-        validationError.message,
-        null,
-        2
-      )}\n`,
+      )} Validation errors found in OpenAPI Description: \n`,
       this.logTypes.ERROR
     );
+
+    for (const error of validationError) {
+      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/models/BasicDocumentation.json

@@ -1,30 +1,48 @@
 {
-    "custom": {
-        "documentation": {
-            "title": "test-service",
-            "models": [
-                {
-                    "name": "SuccessResponse",
-                    "description": "Success response",
-                    "content": {
-                        "application/json": {
-                            "schema": {
-                                "$schema": "http://json-schema.org/draft-04/schema#",
-                                "properties": {
-                                    "SomeObject": {
-                                        "type": "object",
-                                        "properties": {
-                                            "SomeAttribute": {
-                                                "type": "string"
-                                            }
-                                        }
-                                    }
-                                }
-                            }
-                        }
+  "custom": {
+    "documentation": {
+      "title": "test-service",
+      "models": [
+        {
+          "name": "SuccessResponse",
+          "description": "Success response",
+          "content": {
+            "application/json": {
+              "schema": {
+                "$schema": "http://json-schema.org/draft-04/schema#",
+                "type": "object",
+                "properties": {
+                  "SomeObject": {
+                    "type": "object",
+                    "properties": {
+                      "SomeAttribute": {
+                        "type": "string"
+                      }
                     }
+                  }
                 }
-            ]
+              }
+            }
+          }
+        },
+        {
+          "name": "ErrorResponse",
+          "description": "Error response",
+          "content": {
+            "application/json": {
+              "schema": {
+                "$schema": "http://json-schema.org/draft-04/schema#",
+                "type": "object",
+                "properties": {
+                  "error": {
+                    "type": "string"
+                  }
+                }
+              }
+            }
+          }
         }
+      ]
     }
+  }
 }

package/test/models/BasicValidFunction.json

@@ -1,35 +1,44 @@
 {
-    "createUser": {
-        "name": "createUser",
-        "handler": "handler.create",
-        "events": [
-            {
-                "http": {
-                    "path": "find/{name}",
-                    "method": "get",
-                    "documentation": {
-                        "pathParams": [
-                            {
-                                "name": "name",
-                                "schema": {
-                                    "type": "string"
-                                }
-                            }
-                        ],
-                        "methodResponses": [
-                            {
-                                "statusCode": 200,
-                                "responseBody": {
-                                    "description": "A user object along with generated API Keys"
-                                },
-                                "responseModels": {
-                                    "application/json": "SuccessResponse"
-                                }
-                            }
-                        ]
-                    }
+  "createUser": {
+    "name": "createUser",
+    "handler": "handler.create",
+    "events": [
+      {
+        "http": {
+          "path": "find/{name}",
+          "method": "get",
+          "documentation": {
+            "pathParams": [
+              {
+                "name": "name",
+                "schema": {
+                  "type": "string"
                 }
-            }
-        ]
-    }
+              }
+            ],
+            "methodResponses": [
+              {
+                "statusCode": 200,
+                "responseBody": {
+                  "description": "A user object along with generated API Keys"
+                },
+                "responseModels": {
+                  "application/json": "SuccessResponse"
+                }
+              },
+              {
+                "statusCode": 400,
+                "responseBody": {
+                  "description": "An Error"
+                },
+                "responseModels": {
+                  "application/json": "ErrorResponse"
+                }
+              }
+            ]
+          }
+        }
+      }
+    ]
+  }
 }

package/test/unit/openAPIGenerator.spec.js

@@ -187,8 +187,12 @@ describe("OpenAPIGenerator", () => {
       const validOpenAPIDocument = await openAPIGenerator
         .generationAndValidation()
         .catch((err) => {
-          expect(err.message).to.be.equal(
-            "AssertionError: Templated parameter name not found"
+          // expect(err.message).to.be.equal(
+          //   `Error validating OpenAPI Description:\r\nThe operation does not define the path parameter \`{name}\` expected by path \`/find/{name}\`.`
+          // );
+          expect(err).to.have.property("message");
+          expect(err.message).to.include(
+            "Error validating OpenAPI Description:"
           );
         });