From a0e2f33d90ec7366277ed4a98d5b0cb3a3c528aa Mon Sep 17 00:00:00 2001 From: Jared Evans Date: Wed, 24 Sep 2025 16:55:33 +0100 Subject: [PATCH 01/26] updates OWASP headers --- README.md | 1 + json/owasp.json | 8 ++++++-- src/owasp.js | 5 +++++ 3 files changed, 12 insertions(+), 2 deletions(-) diff --git a/README.md b/README.md index 55fd985..7a20d2c 100644 --- a/README.md +++ b/README.md @@ -980,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. diff --git a/json/owasp.json b/json/owasp.json index 0b0e2ae..37c9a53 100644 --- a/json/owasp.json +++ b/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" diff --git a/src/owasp.js b/src/owasp.js index 5189e5c..e4d4840 100644 --- a/src/owasp.js +++ b/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", }; } From 6db93996df6c7534b4d67c037e8753389e05a9b9 Mon Sep 17 00:00:00 2001 From: Jared Evans Date: Wed, 24 Sep 2025 16:55:48 +0100 Subject: [PATCH 02/26] 0.0.116 --- package-lock.json | 4 ++-- package.json | 2 +- 2 files changed, 3 insertions(+), 3 deletions(-) diff --git a/package-lock.json b/package-lock.json index 320aa3d..202be7c 100644 --- a/package-lock.json +++ b/package-lock.json @@ -1,12 +1,12 @@ { "name": "serverless-openapi-documenter", - "version": "0.0.115", + "version": "0.0.116", "lockfileVersion": 2, "requires": true, "packages": { "": { "name": "serverless-openapi-documenter", - "version": "0.0.115", + "version": "0.0.116", "license": "MIT", "dependencies": { "@apidevtools/json-schema-ref-parser": "^9.1.0", diff --git a/package.json b/package.json index 5b0d2b8..0b5d04c 100644 --- a/package.json +++ b/package.json @@ -1,6 +1,6 @@ { "name": "serverless-openapi-documenter", - "version": "0.0.115", + "version": "0.0.116", "description": "Generate OpenAPI v3 documentation and Postman Collections from your Serverless Config", "main": "index.js", "keywords": [ From e5627a808e136df170ab7f996cf0c181eb623e5f Mon Sep 17 00:00:00 2001 From: Jared Evans Date: Thu, 25 Sep 2025 08:44:08 +0100 Subject: [PATCH 03/26] update documentation --- README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/README.md b/README.md index 7a20d2c..a00d233 100644 --- a/README.md +++ b/README.md @@ -930,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. From 4a8942ac1044e018989afebece5f37b1541ecb1b Mon Sep 17 00:00:00 2001 From: Jared Evans Date: Thu, 25 Sep 2025 08:44:20 +0100 Subject: [PATCH 04/26] 0.0.117 --- package-lock.json | 4 ++-- package.json | 2 +- 2 files changed, 3 insertions(+), 3 deletions(-) diff --git a/package-lock.json b/package-lock.json index 202be7c..93f0cd9 100644 --- a/package-lock.json +++ b/package-lock.json @@ -1,12 +1,12 @@ { "name": "serverless-openapi-documenter", - "version": "0.0.116", + "version": "0.0.117", "lockfileVersion": 2, "requires": true, "packages": { "": { "name": "serverless-openapi-documenter", - "version": "0.0.116", + "version": "0.0.117", "license": "MIT", "dependencies": { "@apidevtools/json-schema-ref-parser": "^9.1.0", diff --git a/package.json b/package.json index 0b5d04c..9e266de 100644 --- a/package.json +++ b/package.json @@ -1,6 +1,6 @@ { "name": "serverless-openapi-documenter", - "version": "0.0.116", + "version": "0.0.117", "description": "Generate OpenAPI v3 documentation and Postman Collections from your Serverless Config", "main": "index.js", "keywords": [ From dd7cdfcafcad9914ab0a816c4c21ce35b5d18ccd Mon Sep 17 00:00:00 2001 From: Jared Evans Date: Thu, 20 Nov 2025 11:53:18 +0000 Subject: [PATCH 05/26] updates js-yaml to 4.1.1 and updates openapi-to-postmanv2 to 5.4.1 --- package-lock.json | 72 +++++++++++++++++++++++++++++++---------------- package.json | 4 +-- 2 files changed, 50 insertions(+), 26 deletions(-) diff --git a/package-lock.json b/package-lock.json index 93f0cd9..cd99aeb 100644 --- a/package-lock.json +++ b/package-lock.json @@ -12,9 +12,9 @@ "@apidevtools/json-schema-ref-parser": "^9.1.0", "@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" }, "devDependencies": { @@ -296,9 +296,10 @@ } }, "node_modules/async": { - "version": "3.2.4", - "resolved": "https://registry.npmjs.org/async/-/async-3.2.4.tgz", - "integrity": "sha512-iAB+JbDEGXhyIUavoDl9WP/Jj106Kz9DEn1DPgYw5ruDn0e3Wgi3sKFm55sASdGBNOQB8F59d9qQ7deqrHA8wQ==" + "version": "3.2.6", + "resolved": "https://registry.npmjs.org/async/-/async-3.2.6.tgz", + "integrity": "sha512-htCUDlxyyCLMgaM3xXg0C0LW2xqfuQ6p05pCEIsXuyQ+a1koYKTuBMzRNwmybfLgvJDMd0r1LTn4+E0Ti6C2AA==", + "license": "MIT" }, "node_modules/balanced-match": { "version": "1.0.2", @@ -875,9 +876,10 @@ } }, "node_modules/js-yaml": { - "version": "4.1.0", - "resolved": "https://registry.npmjs.org/js-yaml/-/js-yaml-4.1.0.tgz", - "integrity": "sha512-wpxZs9NoxZaJESJGIZTyDEaYpl0FKSA+FB9aJiyemKhMwkxQg63h4T1KJgUGHpTqPDNRcmmYLugrRjJlBtWvRA==", + "version": "4.1.1", + "resolved": "https://registry.npmjs.org/js-yaml/-/js-yaml-4.1.1.tgz", + "integrity": "sha512-qQKT4zQxXl8lLwBtHMWwaTcGfFOZviOJet3Oy/xmGk2gZH677CJM9EvtfdSkgWcATZhj/55JZ0rmy3myCT5lsA==", + "license": "MIT", "dependencies": { "argparse": "^2.0.1" }, @@ -1301,15 +1303,15 @@ } }, "node_modules/openapi-to-postmanv2": { - "version": "5.3.0", - "resolved": "https://registry.npmjs.org/openapi-to-postmanv2/-/openapi-to-postmanv2-5.3.0.tgz", - "integrity": "sha512-ozJvm946pKaHvilgvDZGC95Hgl2UmNAA5FL6NE33VQORd6rmAaRyavHwyW7i5aEKm2XnTfgM51kSA+8LbMTlBQ==", + "version": "5.4.1", + "resolved": "https://registry.npmjs.org/openapi-to-postmanv2/-/openapi-to-postmanv2-5.4.1.tgz", + "integrity": "sha512-cuPnRZphMS6QsjKa+ktJ9wYXYvAHtl5WyTCodtraASOp4pe6wVcoA9mEs8VHDFZvzYeZ8t7wAQ2faYiw9PsWhQ==", "license": "Apache-2.0", "dependencies": { - "ajv": "8.11.0", + "ajv": "^8.11.0", "ajv-draft-04": "1.0.0", "ajv-formats": "2.1.1", - "async": "3.2.4", + "async": "3.2.6", "commander": "2.20.3", "graphlib": "2.1.8", "js-yaml": "4.1.0", @@ -1331,6 +1333,18 @@ "node": ">=18" } }, + "node_modules/openapi-to-postmanv2/node_modules/js-yaml": { + "version": "4.1.0", + "resolved": "https://registry.npmjs.org/js-yaml/-/js-yaml-4.1.0.tgz", + "integrity": "sha512-wpxZs9NoxZaJESJGIZTyDEaYpl0FKSA+FB9aJiyemKhMwkxQg63h4T1KJgUGHpTqPDNRcmmYLugrRjJlBtWvRA==", + "license": "MIT", + "dependencies": { + "argparse": "^2.0.1" + }, + "bin": { + "js-yaml": "bin/js-yaml.js" + } + }, "node_modules/outvariant": { "version": "1.4.3", "resolved": "https://registry.npmjs.org/outvariant/-/outvariant-1.4.3.tgz", @@ -2382,9 +2396,9 @@ "dev": true }, "async": { - "version": "3.2.4", - "resolved": "https://registry.npmjs.org/async/-/async-3.2.4.tgz", - "integrity": "sha512-iAB+JbDEGXhyIUavoDl9WP/Jj106Kz9DEn1DPgYw5ruDn0e3Wgi3sKFm55sASdGBNOQB8F59d9qQ7deqrHA8wQ==" + "version": "3.2.6", + "resolved": "https://registry.npmjs.org/async/-/async-3.2.6.tgz", + "integrity": "sha512-htCUDlxyyCLMgaM3xXg0C0LW2xqfuQ6p05pCEIsXuyQ+a1koYKTuBMzRNwmybfLgvJDMd0r1LTn4+E0Ti6C2AA==" }, "balanced-match": { "version": "1.0.2", @@ -2798,9 +2812,9 @@ "integrity": "sha512-X2BB11YZtrRqY4EnQcLX5Rh373zbK4alC1FW7D7MBhL2gtcC17cTnr6DmfHZeS0s2rTHjUTMMHfG7gO8SSdw+g==" }, "js-yaml": { - "version": "4.1.0", - "resolved": "https://registry.npmjs.org/js-yaml/-/js-yaml-4.1.0.tgz", - "integrity": "sha512-wpxZs9NoxZaJESJGIZTyDEaYpl0FKSA+FB9aJiyemKhMwkxQg63h4T1KJgUGHpTqPDNRcmmYLugrRjJlBtWvRA==", + "version": "4.1.1", + "resolved": "https://registry.npmjs.org/js-yaml/-/js-yaml-4.1.1.tgz", + "integrity": "sha512-qQKT4zQxXl8lLwBtHMWwaTcGfFOZviOJet3Oy/xmGk2gZH677CJM9EvtfdSkgWcATZhj/55JZ0rmy3myCT5lsA==", "requires": { "argparse": "^2.0.1" } @@ -3117,14 +3131,14 @@ "integrity": "sha512-RSn9F68PjH9HqtltsSnqYC1XXoWe9Bju5+213R98cNGttag9q9yAOTzdbsqvIa7aNm5WffBZFpWYr2aWrklWAw==" }, "openapi-to-postmanv2": { - "version": "5.3.0", - "resolved": "https://registry.npmjs.org/openapi-to-postmanv2/-/openapi-to-postmanv2-5.3.0.tgz", - "integrity": "sha512-ozJvm946pKaHvilgvDZGC95Hgl2UmNAA5FL6NE33VQORd6rmAaRyavHwyW7i5aEKm2XnTfgM51kSA+8LbMTlBQ==", + "version": "5.4.1", + "resolved": "https://registry.npmjs.org/openapi-to-postmanv2/-/openapi-to-postmanv2-5.4.1.tgz", + "integrity": "sha512-cuPnRZphMS6QsjKa+ktJ9wYXYvAHtl5WyTCodtraASOp4pe6wVcoA9mEs8VHDFZvzYeZ8t7wAQ2faYiw9PsWhQ==", "requires": { - "ajv": "8.11.0", + "ajv": "^8.11.0", "ajv-draft-04": "1.0.0", "ajv-formats": "2.1.1", - "async": "3.2.4", + "async": "3.2.6", "commander": "2.20.3", "graphlib": "2.1.8", "js-yaml": "4.1.0", @@ -3138,6 +3152,16 @@ "postman-collection": "^5.0.0", "swagger2openapi": "7.0.8", "yaml": "1.10.2" + }, + "dependencies": { + "js-yaml": { + "version": "4.1.0", + "resolved": "https://registry.npmjs.org/js-yaml/-/js-yaml-4.1.0.tgz", + "integrity": "sha512-wpxZs9NoxZaJESJGIZTyDEaYpl0FKSA+FB9aJiyemKhMwkxQg63h4T1KJgUGHpTqPDNRcmmYLugrRjJlBtWvRA==", + "requires": { + "argparse": "^2.0.1" + } + } } }, "outvariant": { diff --git a/package.json b/package.json index 9e266de..7ffef12 100644 --- a/package.json +++ b/package.json @@ -48,9 +48,9 @@ "@apidevtools/json-schema-ref-parser": "^9.1.0", "@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": { From 80cc999dffc0cfb2965b230b042070a54c15a98f Mon Sep 17 00:00:00 2001 From: Jared Evans Date: Thu, 20 Nov 2025 11:53:53 +0000 Subject: [PATCH 06/26] 0.0.118 --- package-lock.json | 4 ++-- package.json | 2 +- 2 files changed, 3 insertions(+), 3 deletions(-) diff --git a/package-lock.json b/package-lock.json index cd99aeb..d9581ed 100644 --- a/package-lock.json +++ b/package-lock.json @@ -1,12 +1,12 @@ { "name": "serverless-openapi-documenter", - "version": "0.0.117", + "version": "0.0.118", "lockfileVersion": 2, "requires": true, "packages": { "": { "name": "serverless-openapi-documenter", - "version": "0.0.117", + "version": "0.0.118", "license": "MIT", "dependencies": { "@apidevtools/json-schema-ref-parser": "^9.1.0", diff --git a/package.json b/package.json index 7ffef12..136cc0c 100644 --- a/package.json +++ b/package.json @@ -1,6 +1,6 @@ { "name": "serverless-openapi-documenter", - "version": "0.0.117", + "version": "0.0.118", "description": "Generate OpenAPI v3 documentation and Postman Collections from your Serverless Config", "main": "index.js", "keywords": [ From 7307b4a08aacf81d019a507a9ad7d14989341fab Mon Sep 17 00:00:00 2001 From: Jared Evans Date: Sun, 13 Jul 2025 11:04:44 +0100 Subject: [PATCH 07/26] add a beta workflow --- .github/workflows/npm-publish-beta.yml | 37 ++++++++++++++++++++++++++ 1 file changed, 37 insertions(+) create mode 100644 .github/workflows/npm-publish-beta.yml diff --git a/.github/workflows/npm-publish-beta.yml b/.github/workflows/npm-publish-beta.yml new file mode 100644 index 0000000..bbd3fcc --- /dev/null +++ b/.github/workflows/npm-publish-beta.yml @@ -0,0 +1,37 @@ +# This workflow will run tests using node and then publish a package to GitHub Packages when a release is created +# For more information see: https://help.github.com/actions/language-and-framework-guides/publishing-nodejs-packages + +name: Node.js Beta Package + +on: + push: + branches: + - beta # Or your beta branch name + +jobs: + build: + runs-on: ubuntu-latest + steps: + - uses: actions/checkout@v3 + - uses: actions/setup-node@v3 + with: + node-version: 20 + - run: npm ci + # - run: npm test + + publish-beta-npm: + needs: build + runs-on: ubuntu-latest + steps: + - uses: actions/checkout@v3 + - uses: actions/setup-node@v3 + with: + node-version: 20 + registry-url: https://registry.npmjs.org/ + - run: npm ci + - name: Bump version and publish + env: + NODE_AUTH_TOKEN: ${{secrets.npm_token}} + run: | + npm version prerelease --preid beta + npm publish --tag beta From b4fff722d0c272f93c87815563de0a18c18d1e25 Mon Sep 17 00:00:00 2001 From: Jared Evans Date: Sun, 13 Jul 2025 11:13:29 +0100 Subject: [PATCH 08/26] don't use version --- .github/workflows/npm-publish-beta.yml | 4 +--- 1 file changed, 1 insertion(+), 3 deletions(-) diff --git a/.github/workflows/npm-publish-beta.yml b/.github/workflows/npm-publish-beta.yml index bbd3fcc..d90e996 100644 --- a/.github/workflows/npm-publish-beta.yml +++ b/.github/workflows/npm-publish-beta.yml @@ -30,8 +30,6 @@ jobs: registry-url: https://registry.npmjs.org/ - run: npm ci - name: Bump version and publish + run: npm publish --tag beta env: NODE_AUTH_TOKEN: ${{secrets.npm_token}} - run: | - npm version prerelease --preid beta - npm publish --tag beta From a843665a57ec95115e3709e92939a4ffd25f842d Mon Sep 17 00:00:00 2001 From: Jared Evans Date: Sun, 13 Jul 2025 10:04:56 +0100 Subject: [PATCH 09/26] We shouldn't need to convert schemas for 3.1.x --- src/schemaHandler.js | 20 ++++++++++++++------ 1 file changed, 14 insertions(+), 6 deletions(-) diff --git a/src/schemaHandler.js b/src/schemaHandler.js index d66bc61..ccfb69d 100644 --- a/src/schemaHandler.js +++ b/src/schemaHandler.js @@ -15,6 +15,8 @@ class SchemaHandler { serverless.service?.provider?.apiGateway?.request?.schemas || {}; this.documentation = serverless.service.custom.documentation; this.openAPI = openAPI; + this.shouldConvert = true; + if (/(3\.1\.\d)/g(this.openAPI.openapi)) this.shouldConvert = false; this.modelReferences = {}; @@ -161,14 +163,20 @@ class SchemaHandler { `dereferenced model: ${JSON.stringify(dereferencedSchema)}` ); - this.logger.verbose(`converting model: ${name}`); - const convertedSchemas = SchemaConvertor.convert(dereferencedSchema, name); + if (this.shouldConvert) { + this.logger.verbose(`converting model: ${name}`); + const convertedSchemas = SchemaConvertor.convert( + dereferencedSchema, + name + ); - this.logger.verbose( - `converted schemas: ${JSON.stringify(convertedSchemas)}` - ); + this.logger.verbose( + `converted schemas: ${JSON.stringify(convertedSchemas)}` + ); + return convertedSchemas; + } - return convertedSchemas; + return dereferencedSchema; } async __dereferenceSchema(schema) { From 88c2111f617ba106a76df9315dc159814a4dd3ca Mon Sep 17 00:00:00 2001 From: Jared Evans Date: Sun, 13 Jul 2025 10:16:53 +0100 Subject: [PATCH 10/26] add to README --- README.md | 2 ++ 1 file changed, 2 insertions(+) diff --git a/README.md b/README.md index a00d233..4abc42d 100644 --- a/README.md +++ b/README.md @@ -14,6 +14,8 @@ 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. +If you are using the beta of 0.0.115, it will now try and create OpenAPI V3.1 (3.1.x) specs for you. 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) + Originally based off of: https://github.com/temando/serverless-openapi-documentation ## Install From a7abe8b6c2a94a344400204a1fe3bb262c287504 Mon Sep 17 00:00:00 2001 From: Jared Evans Date: Sun, 13 Jul 2025 10:43:31 +0100 Subject: [PATCH 11/26] adds tests and fixes case --- test/unit/schemaHandler.spec.js | 114 ++++++++++++++++++++++++++++++-- 1 file changed, 107 insertions(+), 7 deletions(-) diff --git a/test/unit/schemaHandler.spec.js b/test/unit/schemaHandler.spec.js index d5a1cbc..4d08732 100644 --- a/test/unit/schemaHandler.spec.js +++ b/test/unit/schemaHandler.spec.js @@ -4,7 +4,9 @@ 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"); @@ -36,7 +38,7 @@ describe(`SchemaHandler`, function () { ); const openAPISchema = { - version: "3.0.3", + openapi: "3.0.3", components: { schemas: {}, }, @@ -277,7 +279,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 @@ -306,7 +308,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 @@ -379,7 +381,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 @@ -446,7 +448,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 @@ -517,10 +519,86 @@ 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 @@ -589,7 +667,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 @@ -710,6 +788,28 @@ 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, From 694224eb95158464cf16592d7dff647b1e084819 Mon Sep 17 00:00:00 2001 From: Jared Evans Date: Sun, 13 Jul 2025 10:43:57 +0100 Subject: [PATCH 12/26] fixes casing of OpenAPI --- test/unit/definitionGenerator.spec.js | 11 ++++++----- test/unit/openAPIGenerator.spec.js | 10 +++++----- 2 files changed, 11 insertions(+), 10 deletions(-) diff --git a/test/unit/definitionGenerator.spec.js b/test/unit/definitionGenerator.spec.js index 65b76f9..950d024 100644 --- a/test/unit/definitionGenerator.spec.js +++ b/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,14 +918,15 @@ 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( diff --git a/test/unit/openAPIGenerator.spec.js b/test/unit/openAPIGenerator.spec.js index 4436083..cbffbcc 100644 --- a/test/unit/openAPIGenerator.spec.js +++ b/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"); From 8a11949d713d618e1070780d5290e9268befdb98 Mon Sep 17 00:00:00 2001 From: Jared Evans Date: Sun, 13 Jul 2025 10:44:13 +0100 Subject: [PATCH 13/26] check whether we should try and convert an OpenAPI schema --- src/schemaHandler.js | 19 +++++++++++++------ 1 file changed, 13 insertions(+), 6 deletions(-) diff --git a/src/schemaHandler.js b/src/schemaHandler.js index ccfb69d..71fc33e 100644 --- a/src/schemaHandler.js +++ b/src/schemaHandler.js @@ -15,8 +15,9 @@ class SchemaHandler { serverless.service?.provider?.apiGateway?.request?.schemas || {}; this.documentation = serverless.service.custom.documentation; this.openAPI = openAPI; + this.shouldConvert = true; - if (/(3\.1\.\d)/g(this.openAPI.openapi)) this.shouldConvert = false; + if (/(3\.1\.\d)/g.test(this.openAPI.openapi)) this.shouldConvert = false; this.modelReferences = {}; @@ -159,11 +160,11 @@ class SchemaHandler { } ); - this.logger.verbose( - `dereferenced model: ${JSON.stringify(dereferencedSchema)}` - ); - if (this.shouldConvert) { + this.logger.verbose( + `dereferenced model: ${JSON.stringify(dereferencedSchema)}` + ); + this.logger.verbose(`converting model: ${name}`); const convertedSchemas = SchemaConvertor.convert( dereferencedSchema, @@ -176,7 +177,13 @@ class SchemaHandler { return convertedSchemas; } - return dereferencedSchema; + this.logger.verbose( + `dereferenced model: ${JSON.stringify({ + schemas: { [name]: dereferencedSchema }, + })}` + ); + + return { schemas: { [name]: dereferencedSchema } }; } async __dereferenceSchema(schema) { From ef23686d1c2cda0579e07ca9cf60402bdcb57198 Mon Sep 17 00:00:00 2001 From: Jared Evans Date: Sun, 13 Jul 2025 10:45:35 +0100 Subject: [PATCH 14/26] update README with warning --- README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/README.md b/README.md index 4abc42d..756c390 100644 --- a/README.md +++ b/README.md @@ -14,7 +14,7 @@ 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. -If you are using the beta of 0.0.115, it will now try and create OpenAPI V3.1 (3.1.x) specs for you. 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) +If you are using the beta of 0.0.115, it will now try and create OpenAPI V3.1 (3.1.x) specs for you. 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. Originally based off of: https://github.com/temando/serverless-openapi-documentation From 76ef5a4dc73a7eb8359496a86b803e12145e1faa Mon Sep 17 00:00:00 2001 From: Jared Evans Date: Sun, 13 Jul 2025 11:22:23 +0100 Subject: [PATCH 15/26] improve README --- README.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/README.md b/README.md index 756c390..e0e03d1 100644 --- a/README.md +++ b/README.md @@ -12,9 +12,9 @@

-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. +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) specs for you. 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. +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. Originally based off of: https://github.com/temando/serverless-openapi-documentation From c60b6dad151ce8f4ca9b7e8b9677ae4cf39f7f5f Mon Sep 17 00:00:00 2001 From: Jared Evans Date: Mon, 28 Jul 2025 12:31:01 +0100 Subject: [PATCH 16/26] updates redocly-core to latest version 1 --- package-lock.json | 74 +++++++++++++++++++++++++++++++---------------- package.json | 2 +- 2 files changed, 50 insertions(+), 26 deletions(-) diff --git a/package-lock.json b/package-lock.json index d9581ed..eaf9893 100644 --- a/package-lock.json +++ b/package-lock.json @@ -10,7 +10,7 @@ "license": "MIT", "dependencies": { "@apidevtools/json-schema-ref-parser": "^9.1.0", - "@redocly/openapi-core": "^1.2.0", + "@redocly/openapi-core": "^1.34.5", "chalk": "^4.1.2", "js-yaml": "^4.1.1", "json-schema-for-openapi": "^0.5.0", @@ -128,38 +128,46 @@ } }, "node_modules/@redocly/ajv": { - "version": "8.11.0", - "resolved": "https://registry.npmjs.org/@redocly/ajv/-/ajv-8.11.0.tgz", - "integrity": "sha512-9GWx27t7xWhDIR02PA18nzBdLcKQRgc46xNQvjFkrYk4UOmvKhJ/dawwiX0cCOeetN5LcaaiqQbVOWYK62SGHw==", + "version": "8.11.3", + "resolved": "https://registry.npmjs.org/@redocly/ajv/-/ajv-8.11.3.tgz", + "integrity": "sha512-4P3iZse91TkBiY+Dx5DUgxQ9GXkVJf++cmI0MOyLDxV9b5MUBI4II6ES8zA5JCbO72nKAJxWrw4PUPW+YP3ZDQ==", + "license": "MIT", "dependencies": { "fast-deep-equal": "^3.1.1", "json-schema-traverse": "^1.0.0", "require-from-string": "^2.0.2", - "uri-js": "^4.2.2" + "uri-js-replace": "^1.0.1" }, "funding": { "type": "github", "url": "https://github.com/sponsors/epoberezkin" } }, + "node_modules/@redocly/config": { + "version": "0.22.2", + "resolved": "https://registry.npmjs.org/@redocly/config/-/config-0.22.2.tgz", + "integrity": "sha512-roRDai8/zr2S9YfmzUfNhKjOF0NdcOIqF7bhf4MVC5UxpjIysDjyudvlAiVbpPHp3eDRWbdzUgtkK1a7YiDNyQ==", + "license": "MIT" + }, "node_modules/@redocly/openapi-core": { - "version": "1.2.0", - "resolved": "https://registry.npmjs.org/@redocly/openapi-core/-/openapi-core-1.2.0.tgz", - "integrity": "sha512-Ccft2n/JiF4u2crmj1cdDzPq6C40U7NgLZ+p/BxzAFXbfrddr/5FN0HMJPHT/op329qqv2P2jUrXsV2Bp+rzEQ==", + "version": "1.34.5", + "resolved": "https://registry.npmjs.org/@redocly/openapi-core/-/openapi-core-1.34.5.tgz", + "integrity": "sha512-0EbE8LRbkogtcCXU7liAyC00n9uNG9hJ+eMyHFdUsy9lB/WGqnEBgwjA9q2cyzAVcdTkQqTBBU1XePNnN3OijA==", + "license": "MIT", "dependencies": { - "@redocly/ajv": "^8.11.0", - "@types/node": "^14.11.8", + "@redocly/ajv": "^8.11.2", + "@redocly/config": "^0.22.0", "colorette": "^1.2.0", + "https-proxy-agent": "^7.0.5", "js-levenshtein": "^1.1.6", "js-yaml": "^4.1.0", - "lodash.isequal": "^4.5.0", "minimatch": "^5.0.1", - "node-fetch": "^2.6.1", "pluralize": "^8.0.0", "yaml-ast-parser": "0.0.43" }, "engines": { - "node": ">=14.0.0" + "node": ">=18.17.0", + "npm": ">=9.5.0" } }, "node_modules/@sinonjs/commons": { @@ -205,10 +213,14 @@ "resolved": "https://registry.npmjs.org/@types/json-schema/-/json-schema-7.0.11.tgz", "integrity": "sha512-wOuvG1SN4Us4rez+tylwwwCV1psiNVOkJeM3AUWUNWg/jDQY2+HE/444y5gc+jBmRqASOm2Oeh5c1axHobwRKQ==" }, - "node_modules/@types/node": { - "version": "14.18.63", - "resolved": "https://registry.npmjs.org/@types/node/-/node-14.18.63.tgz", - "integrity": "sha512-fAtCfv4jJg+ExtXhvCkCqUKZ+4ok/JQk01qDKhL5BDDoS3AxKXhV5/MAVUZyQnSEd2GT92fkgZl0pz0Q0AzcIQ==" + "node_modules/agent-base": { + "version": "7.1.4", + "resolved": "https://registry.npmjs.org/agent-base/-/agent-base-7.1.4.tgz", + "integrity": "sha512-MnA+YT8fwfJPgBx3m60MNqakm30XOkyIoH1y6huTQvC0PwZG7ki8NacLBcrPbNoo8vEZy7Jpuk7+jMO+CUovTQ==", + "license": "MIT", + "engines": { + "node": ">= 14" + } }, "node_modules/ajv": { "version": "8.11.0", @@ -554,7 +566,6 @@ "version": "4.3.7", "resolved": "https://registry.npmjs.org/debug/-/debug-4.3.7.tgz", "integrity": "sha512-Er2nc/H7RrMXZBFCEim6TCmMk02Z8vLC2Rbi1KEBggpo0fS6l0S1nnapwmIi3yW/+GOJap1Krg4w0Hg80oCqgQ==", - "dev": true, "dependencies": { "ms": "^2.1.3" }, @@ -796,6 +807,19 @@ "resolved": "https://registry.npmjs.org/http2-client/-/http2-client-1.3.5.tgz", "integrity": "sha512-EC2utToWl4RKfs5zd36Mxq7nzHHBuomZboI0yYL6Y0RmBgT7Sgkq4rQ0ezFTYoIsSs7Tm9SJe+o2FcAg6GBhGA==" }, + "node_modules/https-proxy-agent": { + "version": "7.0.6", + "resolved": "https://registry.npmjs.org/https-proxy-agent/-/https-proxy-agent-7.0.6.tgz", + "integrity": "sha512-vK9P5/iUfdl95AI+JVyUuIcVtd4ofvtrOr3HNtM2yxC9bnMbEdp3x01OhQNnjb8IJYi38VlTE3mBXwcfvywuSw==", + "license": "MIT", + "dependencies": { + "agent-base": "^7.1.2", + "debug": "4" + }, + "engines": { + "node": ">= 14" + } + }, "node_modules/iconv-lite": { "version": "0.6.3", "resolved": "https://registry.npmjs.org/iconv-lite/-/iconv-lite-0.6.3.tgz", @@ -990,11 +1014,6 @@ "deprecated": "This package is deprecated. Use the optional chaining (?.) operator instead.", "dev": true }, - "node_modules/lodash.isequal": { - "version": "4.5.0", - "resolved": "https://registry.npmjs.org/lodash.isequal/-/lodash.isequal-4.5.0.tgz", - "integrity": "sha512-pDo3lu8Jhfjqls6GkMgpahsF9kCyayhgykjyLMNFTKWrpVdAQtYyB4muAMWozBB4ig/dtWAmsMxLEI8wuz+DYQ==" - }, "node_modules/log-symbols": { "version": "4.1.0", "resolved": "https://registry.npmjs.org/log-symbols/-/log-symbols-4.1.0.tgz", @@ -1146,8 +1165,7 @@ "node_modules/ms": { "version": "2.1.3", "resolved": "https://registry.npmjs.org/ms/-/ms-2.1.3.tgz", - "integrity": "sha512-6FlzubTLZG3J2a/NVCAleEhjzq5oxgHyaCU9yYXvcLsvoVaHJq/s5xXI6/XXP6tz7R9xAOtHnSO/tXtF3WRTlA==", - "dev": true + "integrity": "sha512-6FlzubTLZG3J2a/NVCAleEhjzq5oxgHyaCU9yYXvcLsvoVaHJq/s5xXI6/XXP6tz7R9xAOtHnSO/tXtF3WRTlA==" }, "node_modules/neotraverse": { "version": "0.6.15", @@ -1892,6 +1910,12 @@ "punycode": "^2.1.0" } }, + "node_modules/uri-js-replace": { + "version": "1.0.1", + "resolved": "https://registry.npmjs.org/uri-js-replace/-/uri-js-replace-1.0.1.tgz", + "integrity": "sha512-W+C9NWNLFOoBI2QWDp4UT9pv65r2w5Cx+3sTYFvtMdDBxkKt1syCqsUdSFAChbEe1uK5TfS04wt/nGwmaeIQ0g==", + "license": "MIT" + }, "node_modules/uuid": { "version": "11.1.0", "resolved": "https://registry.npmjs.org/uuid/-/uuid-11.1.0.tgz", diff --git a/package.json b/package.json index 136cc0c..45ede36 100644 --- a/package.json +++ b/package.json @@ -46,7 +46,7 @@ "license": "MIT", "dependencies": { "@apidevtools/json-schema-ref-parser": "^9.1.0", - "@redocly/openapi-core": "^1.2.0", + "@redocly/openapi-core": "^1.34.5", "chalk": "^4.1.2", "js-yaml": "^4.1.1", "json-schema-for-openapi": "^0.5.0", From 39cfa8c12aa19f517d9fe060e890abbe49005375 Mon Sep 17 00:00:00 2001 From: Jared Evans Date: Mon, 28 Jul 2025 12:35:59 +0100 Subject: [PATCH 17/26] should run tests on beta too --- .github/workflows/node.yml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/.github/workflows/node.yml b/.github/workflows/node.yml index 0fcd3be..9fba7b4 100644 --- a/.github/workflows/node.yml +++ b/.github/workflows/node.yml @@ -7,7 +7,7 @@ on: push: branches: ["main"] pull_request: - branches: ["main"] + branches: ["main", "beta"] jobs: build: From 404312a1bf4941913849bc12cd6a63a908dac31b Mon Sep 17 00:00:00 2001 From: Jared Evans Date: Sun, 13 Jul 2025 11:04:44 +0100 Subject: [PATCH 18/26] add a beta workflow --- .github/workflows/npm-publish-beta.yml | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) diff --git a/.github/workflows/npm-publish-beta.yml b/.github/workflows/npm-publish-beta.yml index d90e996..bbd3fcc 100644 --- a/.github/workflows/npm-publish-beta.yml +++ b/.github/workflows/npm-publish-beta.yml @@ -30,6 +30,8 @@ jobs: registry-url: https://registry.npmjs.org/ - run: npm ci - name: Bump version and publish - run: npm publish --tag beta env: NODE_AUTH_TOKEN: ${{secrets.npm_token}} + run: | + npm version prerelease --preid beta + npm publish --tag beta From 7d0a131546ae9daa5c26289d191a88220720e539 Mon Sep 17 00:00:00 2001 From: Jared Evans Date: Sun, 13 Jul 2025 11:13:29 +0100 Subject: [PATCH 19/26] don't use version --- .github/workflows/npm-publish-beta.yml | 4 +--- 1 file changed, 1 insertion(+), 3 deletions(-) diff --git a/.github/workflows/npm-publish-beta.yml b/.github/workflows/npm-publish-beta.yml index bbd3fcc..d90e996 100644 --- a/.github/workflows/npm-publish-beta.yml +++ b/.github/workflows/npm-publish-beta.yml @@ -30,8 +30,6 @@ jobs: registry-url: https://registry.npmjs.org/ - run: npm ci - name: Bump version and publish + run: npm publish --tag beta env: NODE_AUTH_TOKEN: ${{secrets.npm_token}} - run: | - npm version prerelease --preid beta - npm publish --tag beta From 3bb4a042eb0c7ea9e79edc0086d5bbfae184c496 Mon Sep 17 00:00:00 2001 From: Jared Evans Date: Sun, 13 Jul 2025 10:04:56 +0100 Subject: [PATCH 20/26] We shouldn't need to convert schemas for 3.1.x --- src/schemaHandler.js | 11 ++++------- 1 file changed, 4 insertions(+), 7 deletions(-) diff --git a/src/schemaHandler.js b/src/schemaHandler.js index 71fc33e..f14bd61 100644 --- a/src/schemaHandler.js +++ b/src/schemaHandler.js @@ -15,6 +15,8 @@ class SchemaHandler { serverless.service?.provider?.apiGateway?.request?.schemas || {}; this.documentation = serverless.service.custom.documentation; this.openAPI = openAPI; + this.shouldConvert = true; + if (/(3\.1\.\d)/g(this.openAPI.openapi)) this.shouldConvert = false; this.shouldConvert = true; if (/(3\.1\.\d)/g.test(this.openAPI.openapi)) this.shouldConvert = false; @@ -165,6 +167,7 @@ class SchemaHandler { `dereferenced model: ${JSON.stringify(dereferencedSchema)}` ); + if (this.shouldConvert) { this.logger.verbose(`converting model: ${name}`); const convertedSchemas = SchemaConvertor.convert( dereferencedSchema, @@ -177,13 +180,7 @@ class SchemaHandler { return convertedSchemas; } - this.logger.verbose( - `dereferenced model: ${JSON.stringify({ - schemas: { [name]: dereferencedSchema }, - })}` - ); - - return { schemas: { [name]: dereferencedSchema } }; + return dereferencedSchema; } async __dereferenceSchema(schema) { From 9b481963d2e8943eef1f6cd239b606d71e19ebbf Mon Sep 17 00:00:00 2001 From: Jared Evans Date: Sun, 13 Jul 2025 10:16:53 +0100 Subject: [PATCH 21/26] add to README --- README.md | 2 ++ 1 file changed, 2 insertions(+) diff --git a/README.md b/README.md index e0e03d1..4b3319c 100644 --- a/README.md +++ b/README.md @@ -16,6 +16,8 @@ This will generate an [OpenAPI V3](https://spec.openapis.org/oas/v3.0.0.html) (u 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. +If you are using the beta of 0.0.115, it will now try and create OpenAPI V3.1 (3.1.x) specs for you. 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) + Originally based off of: https://github.com/temando/serverless-openapi-documentation ## Install From ba2277cbc44e9bad31eb18eae2f531731f165741 Mon Sep 17 00:00:00 2001 From: Jared Evans Date: Sun, 13 Jul 2025 10:44:13 +0100 Subject: [PATCH 22/26] check whether we should try and convert an OpenAPI schema --- src/schemaHandler.js | 12 +++++++++--- 1 file changed, 9 insertions(+), 3 deletions(-) diff --git a/src/schemaHandler.js b/src/schemaHandler.js index f14bd61..e4f4d28 100644 --- a/src/schemaHandler.js +++ b/src/schemaHandler.js @@ -15,8 +15,9 @@ class SchemaHandler { serverless.service?.provider?.apiGateway?.request?.schemas || {}; this.documentation = serverless.service.custom.documentation; this.openAPI = openAPI; + this.shouldConvert = true; - if (/(3\.1\.\d)/g(this.openAPI.openapi)) this.shouldConvert = false; + if (/(3\.1\.\d)/g.test(this.openAPI.openapi)) this.shouldConvert = false; this.shouldConvert = true; if (/(3\.1\.\d)/g.test(this.openAPI.openapi)) this.shouldConvert = false; @@ -167,7 +168,6 @@ class SchemaHandler { `dereferenced model: ${JSON.stringify(dereferencedSchema)}` ); - if (this.shouldConvert) { this.logger.verbose(`converting model: ${name}`); const convertedSchemas = SchemaConvertor.convert( dereferencedSchema, @@ -180,7 +180,13 @@ class SchemaHandler { return convertedSchemas; } - return dereferencedSchema; + this.logger.verbose( + `dereferenced model: ${JSON.stringify({ + schemas: { [name]: dereferencedSchema }, + })}` + ); + + return { schemas: { [name]: dereferencedSchema } }; } async __dereferenceSchema(schema) { From 6950cfb9688486e73f9294758a7704a2e276d045 Mon Sep 17 00:00:00 2001 From: Jared Evans Date: Sun, 13 Jul 2025 10:45:35 +0100 Subject: [PATCH 23/26] update README with warning --- README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/README.md b/README.md index 4b3319c..cbcde14 100644 --- a/README.md +++ b/README.md @@ -16,7 +16,7 @@ This will generate an [OpenAPI V3](https://spec.openapis.org/oas/v3.0.0.html) (u 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. -If you are using the beta of 0.0.115, it will now try and create OpenAPI V3.1 (3.1.x) specs for you. 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) +If you are using the beta of 0.0.115, it will now try and create OpenAPI V3.1 (3.1.x) specs for you. 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. Originally based off of: https://github.com/temando/serverless-openapi-documentation From 9d40db54ccfe885928af9700b893ed76923d5075 Mon Sep 17 00:00:00 2001 From: Jared Evans Date: Sun, 13 Jul 2025 11:22:23 +0100 Subject: [PATCH 24/26] improve README --- README.md | 2 -- 1 file changed, 2 deletions(-) diff --git a/README.md b/README.md index cbcde14..e0e03d1 100644 --- a/README.md +++ b/README.md @@ -16,8 +16,6 @@ This will generate an [OpenAPI V3](https://spec.openapis.org/oas/v3.0.0.html) (u 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. -If you are using the beta of 0.0.115, it will now try and create OpenAPI V3.1 (3.1.x) specs for you. 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. - Originally based off of: https://github.com/temando/serverless-openapi-documentation ## Install From f61a4ad493c7abe4423a418f4b7edfe7fad33d76 Mon Sep 17 00:00:00 2001 From: Jared Evans Date: Mon, 28 Jul 2025 12:31:01 +0100 Subject: [PATCH 25/26] updates redocly-core to latest version 1 --- package-lock.json | 40 +++++++++++++++++++++------------------- 1 file changed, 21 insertions(+), 19 deletions(-) diff --git a/package-lock.json b/package-lock.json index eaf9893..a0ddb0c 100644 --- a/package-lock.json +++ b/package-lock.json @@ -2295,29 +2295,33 @@ "optional": true }, "@redocly/ajv": { - "version": "8.11.0", - "resolved": "https://registry.npmjs.org/@redocly/ajv/-/ajv-8.11.0.tgz", - "integrity": "sha512-9GWx27t7xWhDIR02PA18nzBdLcKQRgc46xNQvjFkrYk4UOmvKhJ/dawwiX0cCOeetN5LcaaiqQbVOWYK62SGHw==", + "version": "8.11.2", + "resolved": "https://registry.npmjs.org/@redocly/ajv/-/ajv-8.11.2.tgz", + "integrity": "sha512-io1JpnwtIcvojV7QKDUSIuMN/ikdOUd1ReEnUnMKGfDVridQZ31J0MmIuqwuRjWDZfmvr+Q0MqCcfHM2gTivOg==", "requires": { "fast-deep-equal": "^3.1.1", "json-schema-traverse": "^1.0.0", "require-from-string": "^2.0.2", - "uri-js": "^4.2.2" + "uri-js-replace": "^1.0.1" } }, + "@redocly/config": { + "version": "0.22.2", + "resolved": "https://registry.npmjs.org/@redocly/config/-/config-0.22.2.tgz", + "integrity": "sha512-roRDai8/zr2S9YfmzUfNhKjOF0NdcOIqF7bhf4MVC5UxpjIysDjyudvlAiVbpPHp3eDRWbdzUgtkK1a7YiDNyQ==" + }, "@redocly/openapi-core": { - "version": "1.2.0", - "resolved": "https://registry.npmjs.org/@redocly/openapi-core/-/openapi-core-1.2.0.tgz", - "integrity": "sha512-Ccft2n/JiF4u2crmj1cdDzPq6C40U7NgLZ+p/BxzAFXbfrddr/5FN0HMJPHT/op329qqv2P2jUrXsV2Bp+rzEQ==", + "version": "1.34.5", + "resolved": "https://registry.npmjs.org/@redocly/openapi-core/-/openapi-core-1.34.5.tgz", + "integrity": "sha512-0EbE8LRbkogtcCXU7liAyC00n9uNG9hJ+eMyHFdUsy9lB/WGqnEBgwjA9q2cyzAVcdTkQqTBBU1XePNnN3OijA==", "requires": { - "@redocly/ajv": "^8.11.0", - "@types/node": "^14.11.8", + "@redocly/ajv": "^8.11.2", + "@redocly/config": "^0.22.0", "colorette": "^1.2.0", + "https-proxy-agent": "^7.0.5", "js-levenshtein": "^1.1.6", "js-yaml": "^4.1.0", - "lodash.isequal": "^4.5.0", "minimatch": "^5.0.1", - "node-fetch": "^2.6.1", "pluralize": "^8.0.0", "yaml-ast-parser": "0.0.43" } @@ -2618,7 +2622,6 @@ "version": "4.3.7", "resolved": "https://registry.npmjs.org/debug/-/debug-4.3.7.tgz", "integrity": "sha512-Er2nc/H7RrMXZBFCEim6TCmMk02Z8vLC2Rbi1KEBggpo0fS6l0S1nnapwmIi3yW/+GOJap1Krg4w0Hg80oCqgQ==", - "dev": true, "requires": { "ms": "^2.1.3" } @@ -2927,11 +2930,6 @@ "integrity": "sha512-z+Uw/vLuy6gQe8cfaFWD7p0wVv8fJl3mbzXh33RS+0oW2wvUqiRXiQ69gLWSLpgB5/6sU+r6BlQR0MBILadqTQ==", "dev": true }, - "lodash.isequal": { - "version": "4.5.0", - "resolved": "https://registry.npmjs.org/lodash.isequal/-/lodash.isequal-4.5.0.tgz", - "integrity": "sha512-pDo3lu8Jhfjqls6GkMgpahsF9kCyayhgykjyLMNFTKWrpVdAQtYyB4muAMWozBB4ig/dtWAmsMxLEI8wuz+DYQ==" - }, "log-symbols": { "version": "4.1.0", "resolved": "https://registry.npmjs.org/log-symbols/-/log-symbols-4.1.0.tgz", @@ -3043,8 +3041,7 @@ "ms": { "version": "2.1.3", "resolved": "https://registry.npmjs.org/ms/-/ms-2.1.3.tgz", - "integrity": "sha512-6FlzubTLZG3J2a/NVCAleEhjzq5oxgHyaCU9yYXvcLsvoVaHJq/s5xXI6/XXP6tz7R9xAOtHnSO/tXtF3WRTlA==", - "dev": true + "integrity": "sha512-6FlzubTLZG3J2a/NVCAleEhjzq5oxgHyaCU9yYXvcLsvoVaHJq/s5xXI6/XXP6tz7R9xAOtHnSO/tXtF3WRTlA==" }, "neotraverse": { "version": "0.6.15", @@ -3571,6 +3568,11 @@ "punycode": "^2.1.0" } }, + "uri-js-replace": { + "version": "1.0.1", + "resolved": "https://registry.npmjs.org/uri-js-replace/-/uri-js-replace-1.0.1.tgz", + "integrity": "sha512-W+C9NWNLFOoBI2QWDp4UT9pv65r2w5Cx+3sTYFvtMdDBxkKt1syCqsUdSFAChbEe1uK5TfS04wt/nGwmaeIQ0g==" + }, "uuid": { "version": "11.1.0", "resolved": "https://registry.npmjs.org/uuid/-/uuid-11.1.0.tgz", From 04c1ec434b77311ec8f708aef6acb4bc915f75b2 Mon Sep 17 00:00:00 2001 From: Jared Evans Date: Thu, 20 Nov 2025 12:30:02 +0000 Subject: [PATCH 26/26] 0.0.118-beta.1 --- package-lock.json | 4 ++-- package.json | 2 +- 2 files changed, 3 insertions(+), 3 deletions(-) diff --git a/package-lock.json b/package-lock.json index a0ddb0c..3c0a418 100644 --- a/package-lock.json +++ b/package-lock.json @@ -1,12 +1,12 @@ { "name": "serverless-openapi-documenter", - "version": "0.0.118", + "version": "0.0.118-beta.1", "lockfileVersion": 2, "requires": true, "packages": { "": { "name": "serverless-openapi-documenter", - "version": "0.0.118", + "version": "0.0.118-beta.1", "license": "MIT", "dependencies": { "@apidevtools/json-schema-ref-parser": "^9.1.0", diff --git a/package.json b/package.json index 45ede36..d320a16 100644 --- a/package.json +++ b/package.json @@ -1,6 +1,6 @@ { "name": "serverless-openapi-documenter", - "version": "0.0.118", + "version": "0.0.118-beta.1", "description": "Generate OpenAPI v3 documentation and Postman Collections from your Serverless Config", "main": "index.js", "keywords": [