serverless-openapi-documenter 0.0.117-beta.1 → 0.0.118

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) from the OpenAPI file for you too. This currently works for `http` and `httpApi` configurations.
 
 Originally based off of: https://github.com/temando/serverless-openapi-documentation
 
@@ -932,7 +930,7 @@ The generator will interpret your settings for CORS and automatically add the re
 
 You can make use of the [OWASP Secure Headers](https://owasp.org/www-project-secure-headers/#x-permitted-cross-domain-policies) to generate response headers. These are a selection of response headers with default values that OWASP recommends returning with your response to help secure your application.
 
-The OWASP Secure Headers Project contains a set of recommended headers to return with recommended values, when generating the documentation, the generator will attempt to get the latest version of this document and apply the latest recommendations. If you do not allow outside connections, it will default to a version of recommendations from **2024-09-19 21:29:28 UTC**.
+The OWASP Secure Headers Project contains a set of recommended headers to return with recommended values, when generating the documentation, the generator will attempt to get the latest version of this document and apply the latest recommendations. If you do not allow outside connections, it will default to a version of recommendations from **2025-08-17 15:23:47 UTC**.
 
 Like CORS, if you have already set any of the OWASP Secure headers via `responseHeaders`, it will not overwrite them.
 
@@ -982,6 +980,7 @@ The full list of OWASP Secure Headers you can set are:
 - xContentTypeOptions - X-Content-Type-Options,
 - xFrameOptions - X-Frame-Options,
 - xPermittedCrossDomainPolicies - X-Permitted-Cross-Domain-Policies
+- xDNSPrefetchControl - X-DNS-Prefetch-Control
 
 You should note that `Pragma` has been [deprecated by owasp](https://owasp.org/www-project-secure-headers/#pragma), this plugin will issue a warning when you are still using Pragma and might drop support.
 

package/json/owasp.json

@@ -1,5 +1,5 @@
 {
-  "last_update_utc": "2024-09-19 21:29:28",
+  "last_update_utc": "2025-08-17 15:23:47",
   "headers": [
     {
       "name": "Cache-Control",
@@ -11,7 +11,7 @@
     },
     {
       "name": "Content-Security-Policy",
-      "value": "default-src 'self'; form-action 'self'; object-src 'none'; frame-ancestors 'none'; upgrade-insecure-requests; block-all-mixed-content"
+      "value": "default-src 'self'; form-action 'self'; base-uri 'self'; object-src 'none'; frame-ancestors 'none'; upgrade-insecure-requests"
     },
     {
       "name": "Cross-Origin-Embedder-Policy",
@@ -41,6 +41,10 @@
       "name": "X-Content-Type-Options",
       "value": "nosniff"
     },
+    {
+      "name": "X-DNS-Prefetch-Control",
+      "value": "off"
+    },
     {
       "name": "X-Frame-Options",
       "value": "deny"

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "serverless-openapi-documenter",
-  "version": "0.0.117-beta.1",
+  "version": "0.0.118",
   "description": "Generate OpenAPI v3 documentation and Postman Collections from your Serverless Config",
   "main": "index.js",
   "keywords": [
@@ -46,11 +46,11 @@
   "license": "MIT",
   "dependencies": {
     "@apidevtools/json-schema-ref-parser": "^9.1.0",
-    "@redocly/openapi-core": "^1.34.5",
+    "@redocly/openapi-core": "^1.2.0",
     "chalk": "^4.1.2",
-    "js-yaml": "^4.1.0",
+    "js-yaml": "^4.1.1",
     "json-schema-for-openapi": "^0.5.0",
-    "openapi-to-postmanv2": "^5.3.0",
+    "openapi-to-postmanv2": "^5.4.1",
     "uuid": "^11.1.0"
   },
   "engines": {

package/src/owasp.js

@@ -67,6 +67,10 @@ class OWASP {
         description:
           "A cross-domain policy file is an XML document that grants a web client, such as Adobe Flash Player or Adobe Acrobat (though not necessarily limited to these), permission to handle data across domains. When clients request content hosted on a particular source domain and that content makes requests directed towards a domain other than its own, the remote domain needs to host a cross-domain policy file that grants access to the source domain, allowing the client to continue the transaction. Normally a meta-policy is declared in the master policy file, but for those who can't write to the root directory, they can also declare a meta-policy using the X-Permitted-Cross-Domain-Policies HTTP response header. - [OWASP Link](https://owasp.org/www-project-secure-headers/#x-permitted-cross-domain-policies)",
       },
+      "X-DNS-Prefetch-Control": {
+        description:
+          "The HTTP X-DNS-Prefetch-Control response header controls DNS prefetching, a feature by which browsers proactively perform domain name resolution on links that the user may choose to follow as well as URLs for items referenced by the document, including images, CSS, JavaScript, and so forth. - [MDN Link](https://developer.mozilla.org/en-US/docs/Web/HTTP/Reference/Headers/X-DNS-Prefetch-Control)",
+      },
     };
 
     this.headerMap = {
@@ -83,6 +87,7 @@ class OWASP {
       xContentTypeOptions: "X-Content-Type-Options",
       xFrameOptions: "X-Frame-Options",
       xPermittedCrossDomainPolicies: "X-Permitted-Cross-Domain-Policies",
+      xDNSPrefetchControl: "X-DNS-Prefetch-Control",
     };
   }
 

package/src/schemaHandler.js

@@ -16,9 +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.modelReferences = {};
 
     this.__standardiseModels();
@@ -160,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/unit/definitionGenerator.spec.js

@@ -38,7 +38,7 @@ describe("DefinitionGenerator", () => {
       expect(expected).to.be.an.instanceOf(DefinitionGenerator);
     });
 
-    it("should default to version 3.0.0 of OpenAPI when OpenAPI version is not passed in", function () {
+    it("should default to version 3.0.0 of openAPI when openAPI version is not passed in", function () {
       const serverlessWithoutOpenAPIVersion = structuredClone(mockServerless);
       delete serverlessWithoutOpenAPIVersion.processedInput;
       let expected = new DefinitionGenerator(
@@ -105,7 +105,7 @@ describe("DefinitionGenerator", () => {
       expect(expected.version).to.be.equal("3.0.0");
     });
 
-    it("should respect the version of OpenAPI when passed in", function () {
+    it("should respect the version of openAPI when passed in", function () {
       const serverlessWithOpenAPIVersion = structuredClone(mockServerless);
       serverlessWithOpenAPIVersion.processedInput.options.openApiVersion =
         "3.0.2";
@@ -157,7 +157,7 @@ describe("DefinitionGenerator", () => {
   });
 
   describe("createInfo", () => {
-    it("should create OpenAPI info object correctly", function () {
+    it("should create openAPI info object correctly", function () {
       const definitionGenerator = new DefinitionGenerator(
         mockServerless,
         logger
@@ -918,15 +918,14 @@ describe("DefinitionGenerator", () => {
           definitionGenerator.openAPI.components.securitySchemes
         ).to.have.property("x_amazon_api_key");
         expect(
-          definitionGenerator.openAPI.components.securitySchemes
-            .x_amazon_api_key
+          definitionGenerator.openAPI.components.securitySchemes.x_amazon_api_key
         ).to.have.property("x-amazon-apigateway-authtype");
       });
     });
   });
 
   describe("createTags", () => {
-    it("should add tags to the OpenAPI object correctly", function () {
+    it("should add tags to the openAPI object correctly", function () {
       mockServerless.service.custom.documentation.tags = [{ name: "tag1" }];
 
       const definitionGenerator = new DefinitionGenerator(

package/test/unit/openAPIGenerator.spec.js

@@ -68,7 +68,7 @@ describe("OpenAPIGenerator", () => {
   });
 
   describe("generationAndValidation", () => {
-    it("should correctly generate a valid OpenAPI document", async function () {
+    it("should correctly generate a valid openAPI document", async function () {
       const succSpy = sinon.spy(logOutput.log, "success");
       const errSpy = sinon.spy(logOutput.log, "error");
 
@@ -99,7 +99,7 @@ describe("OpenAPIGenerator", () => {
       getFuncStub.reset();
     });
 
-    xit("should throw an error when trying to generate an invalid OpenAPI document", async function () {
+    xit("should throw an error when trying to generate an invalid openAPI document", async function () {
       const succSpy = sinon.spy(logOutput.log, "success");
       const errSpy = sinon.spy(logOutput.log, "error");
 
@@ -135,7 +135,7 @@ describe("OpenAPIGenerator", () => {
       getFuncStub.reset();
     });
 
-    it("should correctly validate a valid OpenAPI document", async function () {
+    it("should correctly validate a valid openAPI document", async function () {
       const succSpy = sinon.spy(logOutput.log, "success");
       const errSpy = sinon.spy(logOutput.log, "error");
 
@@ -168,7 +168,7 @@ describe("OpenAPIGenerator", () => {
       getFuncStub.reset();
     });
 
-    it("should throw an error when trying to validate an invalid OpenAPI document", async function () {
+    it("should throw an error when trying to validate an invalid openAPI document", async function () {
       const succSpy = sinon.spy(logOutput.log, "success");
       const errSpy = sinon.spy(logOutput.log, "error");
 
@@ -212,7 +212,7 @@ describe("OpenAPIGenerator", () => {
   });
 
   describe("createPostman", () => {
-    it("should generate a postman collection when a valid OpenAPI file is generated", function () {
+    it("should generate a postman collection when a valid openAPI file is generated", function () {
       const fsStub = sinon.stub(fs, "writeFileSync").returns(true);
       const succSpy = sinon.spy(logOutput.log, "success");
       const errSpy = sinon.spy(logOutput.log, "error");

package/test/unit/schemaHandler.spec.js

@@ -4,9 +4,7 @@ const fs = require("fs").promises;
 const path = require("path");
 
 const expect = require("chai").expect;
-const SchemaConvertor = require("json-schema-for-openapi");
 const nock = require("nock");
-const sinon = require("sinon");
 
 const modelsDocumentOG = require("../models/models/models.json");
 const modelsAltDocumentOG = require("../models/models/models-alt.json");
@@ -38,7 +36,7 @@ describe(`SchemaHandler`, function () {
   );
 
   const openAPISchema = {
-    openapi: "3.0.3",
+    version: "3.0.3",
     components: {
       schemas: {},
     },
@@ -279,7 +277,7 @@ describe(`SchemaHandler`, function () {
 
   describe(`addModelsToOpenAPI`, function () {
     describe(`embedded simple schemas`, function () {
-      it(`should add the model to the OpenAPI schema`, async function () {
+      it(`should add the model to the openAPI schema`, async function () {
         Object.assign(
           mockServerless.service.custom.documentation,
           modelsDocument
@@ -308,7 +306,7 @@ describe(`SchemaHandler`, function () {
         });
       });
 
-      it(`should add a model with references to the OpenAPI schema`, async function () {
+      it(`should add a model with references to the openAPI schema`, async function () {
         Object.assign(
           mockServerless.service.custom.documentation,
           modelsDocument
@@ -381,7 +379,7 @@ describe(`SchemaHandler`, function () {
         });
       });
 
-      it(`should add a model with poorly dereferenced references to the OpenAPI schema`, async function () {
+      it(`should add a model with poorly dereferenced references to the openAPI schema`, async function () {
         Object.assign(
           mockServerless.service.custom.documentation,
           modelsDocument
@@ -448,7 +446,7 @@ describe(`SchemaHandler`, function () {
       });
 
       describe(`component references`, function () {
-        it(`should add schemas with component references to the OpenAPI schema`, async function () {
+        it(`should add schemas with component references to the openAPI schema`, async function () {
           Object.assign(
             mockServerless.service.custom.documentation,
             modelsDocument
@@ -519,86 +517,10 @@ describe(`SchemaHandler`, function () {
             type: "string",
           });
         });
-
-        it(`should add schemas with component references to the OpenAPI schema using OpenAPI 3.1`, async function () {
-          Object.assign(
-            mockServerless.service.custom.documentation,
-            modelsDocument
-          );
-
-          mockServerless.service.custom.documentation.models.push({
-            name: "SuccessResponse",
-            contentType: "application/json",
-            schema: {
-              type: "array",
-              items: {
-                $ref: "#/components/schemas/Agency",
-              },
-            },
-          });
-
-          mockServerless.service.custom.documentation.models.push({
-            name: "Agency",
-            contentType: "application/json",
-            schema: {
-              type: "string",
-            },
-          });
-
-          openAPI.openapi = "3.1.0";
-
-          const schemaHandler = new SchemaHandler(
-            mockServerless,
-            openAPI,
-            logger
-          );
-
-          await schemaHandler.addModelsToOpenAPI();
-
-          expect(schemaHandler.openAPI).to.have.property("components");
-          expect(schemaHandler.openAPI.components).to.have.property("schemas");
-          expect(schemaHandler.openAPI.components.schemas).to.have.property(
-            "ErrorResponse"
-          );
-          expect(
-            schemaHandler.openAPI.components.schemas.ErrorResponse
-          ).to.be.an("object");
-          expect(
-            schemaHandler.openAPI.components.schemas.ErrorResponse
-          ).to.be.eql({
-            type: "object",
-            properties: { error: { type: "string" } },
-          });
-
-          expect(schemaHandler.openAPI.components.schemas).to.have.property(
-            "SuccessResponse"
-          );
-          expect(
-            schemaHandler.openAPI.components.schemas.SuccessResponse
-          ).to.be.an("object");
-          expect(
-            schemaHandler.openAPI.components.schemas.SuccessResponse
-          ).to.be.eql({
-            type: "array",
-            items: {
-              $ref: "#/components/schemas/Agency",
-            },
-          });
-
-          expect(schemaHandler.openAPI.components.schemas).to.have.property(
-            "Agency"
-          );
-          expect(schemaHandler.openAPI.components.schemas.Agency).to.be.an(
-            "object"
-          );
-          expect(schemaHandler.openAPI.components.schemas.Agency).to.be.eql({
-            type: "string",
-          });
-        });
       });
 
       describe(`other references`, function () {
-        it(`should add a model that is a webUrl to the OpenAPI schema`, async function () {
+        it(`should add a model that is a webUrl to the openAPI schema`, async function () {
           Object.assign(
             mockServerless.service.custom.documentation,
             modelsDocument
@@ -667,7 +589,7 @@ describe(`SchemaHandler`, function () {
           });
         });
 
-        it(`should add a complex model that is a webUrl to the OpenAPI schema`, async function () {
+        it(`should add a complex model that is a webUrl to the openAPI schema`, async function () {
           Object.assign(
             mockServerless.service.custom.documentation,
             modelsDocument
@@ -788,28 +710,6 @@ describe(`SchemaHandler`, function () {
   });
 
   describe(`createSchema`, function () {
-    it(`does not convert schemas when using OpenAPI 3.1.x`, async function () {
-      Object.assign(
-        mockServerless.service.custom.documentation,
-        modelsDocument
-      );
-
-      openAPI.openapi = "3.1.0";
-
-      const schemaHandler = new SchemaHandler(mockServerless, openAPI, logger);
-
-      const spy = sinon.spy(SchemaConvertor, "convert");
-
-      await schemaHandler.addModelsToOpenAPI();
-
-      const expected = await schemaHandler.createSchema("ErrorResponse");
-
-      expect(expected).to.be.equal("#/components/schemas/ErrorResponse");
-      expect(spy.calledOnce).to.be.false;
-
-      spy.restore();
-    });
-
     it(`returns a reference to the schema when the schema already exists in components and we don't pass through a schema`, async function () {
       Object.assign(
         mockServerless.service.custom.documentation,