Support OpenAPI 3.1 specs

.eslintignore

@@ -1,2 +1,4 @@
 dist/**
 node_modules/**
+*.cjs
+*.mjs

.eslintrc.json

@@ -4,7 +4,8 @@
     "sourceType": "module"
   },
   "extends": [
-    "@myrotvorets/myrotvorets-ts"
+    "@myrotvorets/myrotvorets-ts",
+    "plugin:mocha/recommended"
   ],
   "env": {
     "es2022": true,

.mocharc.cjs

@@ -3,11 +3,10 @@ module.exports = {
     recursive: true,
     spec: ['test/**/*.test.mts'],
     'node-option': ['loader=ts-node/esm', 'no-warnings'],
-    // require: 'mocha.setup.mjs',
     reporter: 'mocha-multi',
     'reporter-option': [
         'spec=-',
         process.env.GITHUB_ACTIONS === 'true' ? 'mocha-reporter-gha=-' : null,
-        'mocha-reporter-sonarqube=test-report.xml'
+        process.env.SONARSCANNER === 'true' ? 'mocha-reporter-sonarqube=test-report.xml' : null,
     ].filter(Boolean),
 }

lib/index.mts

@@ -1,7 +1,20 @@
 import { middleware } from 'express-openapi-validator';
-import { OpenApiSpecLoader } from 'express-openapi-validator/dist/framework/openapi.spec.loader.js';
+import { OpenApiSpecLoader, type Spec } from 'express-openapi-validator/dist/framework/openapi.spec.loader.js';
 import type { Express } from 'express';
 import type { OpenApiValidatorOpts } from 'express-openapi-validator/dist/openapi.validator.js';
+import type { OpenAPIV3 } from 'express-openapi-validator/dist/framework/types.d.ts';
+
+function loadSpec(doc: OpenAPIV3.Document | string, validate: boolean): Promise<Spec> {
+    const loader = new OpenApiSpecLoader({
+        apiDoc: doc,
+        validateApiSpec: validate,
+        $refParser: {
+            mode: 'dereference',
+        },
+    });
+
+    return loader.load();
+}
 
 export async function installOpenApiValidator(
     specFile: string,
@@ -12,16 +25,32 @@ export async function installOpenApiValidator(
         'apiSpec' | 'validateSecurity' | 'validateResponses' | 'validateFormats' | 'ajvFormats' | '$refParser'
     > = {},
 ): Promise<void> {
-    const loader = new OpenApiSpecLoader({
-        apiDoc: specFile,
-        $refParser: {
-            mode: 'dereference',
-        },
-    });
+    let spec = await loadSpec(specFile, extraOptions.validateApiSpec ?? false);
+    if (spec.apiDoc.openapi.startsWith('3.1.') && extraOptions.validateApiSpec !== false) {
+        // express-openapi-validator does not support OpenAPI 3.1 yet - see https://github.com/cdimascio/express-openapi-validator/issues/755
+        // We make use of `links` in our OpenAPI spec, which is only supported in OpenAPI 3.1
+        spec.apiDoc.openapi = '3.0.3';
+
+        const { paths } = spec.apiDoc;
+        Object.keys(paths).forEach((name) => {
+            const path = paths[name];
+            delete (path.delete as Record<string, unknown> | undefined)?.links;
+            delete (path.get as Record<string, unknown> | undefined)?.links;
+            delete (path.head as Record<string, unknown> | undefined)?.links;
+            delete (path.options as Record<string, unknown> | undefined)?.links;
+            delete (path.patch as Record<string, unknown> | undefined)?.links;
+            delete (path.post as Record<string, unknown> | undefined)?.links;
+            delete (path.put as Record<string, unknown> | undefined)?.links;
+            delete (path.trace as Record<string, unknown> | undefined)?.links;
+        });
+    }
 
-    const spec = await loader.load();
     spec.apiDoc.servers = [{ url: '/' }];
 
+    if (extraOptions.validateApiSpec !== false) {
+        spec = await loadSpec(spec.apiDoc, true);
+    }
+
     const validator = middleware({
         ...extraOptions,
         apiSpec: spec.apiDoc,

package.json

@@ -11,6 +11,7 @@
     "prepare": "npm run build",
     "pretest": "npm run lint",
     "test": "mocha",
+    "pretest:coverage": "npm run lint",
     "test:coverage": "c8 mocha"
   },
   "files": [
@@ -29,6 +30,7 @@
     "@types/supertest": "^2.0.10",
     "c8": "^8.0.1",
     "eslint-formatter-gha": "^1.2.0",
+    "eslint-plugin-mocha": "^10.2.0",
     "express": "^4.17.1",
     "express-openapi-validator": "^5.0.0",
     "mocha": "^10.2.0",

test/index.test.mts

@@ -1,6 +1,6 @@
 import { dirname, join } from 'node:path';
 import { fileURLToPath } from 'node:url';
-import { describe, it } from 'mocha';
+import { doesNotReject } from 'node:assert/strict';
 import express, { type Application, type NextFunction, type Request, type Response } from 'express';
 import request from 'supertest';
 import { installOpenApiValidator } from '../lib/index.mjs';
@@ -32,65 +32,80 @@ async function buildServer(install: boolean, env: string): Promise<Application>
     return app;
 }
 
-describe('Without installOpenApiValidator', () => {
-    it('should return 200 for bad request', async (): Promise<unknown> => {
-        const server = await buildServer(false, '');
-        return request(server).get('/test').expect(200);
-    });
-});
-
-describe('With installOpenApiValidator', () => {
-    it('will not run security handlers', async (): Promise<unknown> => {
-        const server = await buildServer(true, 'test');
-        return request(server).get('/auth').expect(204);
+describe('installOpenApiValidator', function () {
+    describe('Without installOpenApiValidator', function () {
+        it('should return 200 for bad request', async function (): Promise<unknown> {
+            const server = await buildServer(false, '');
+            return request(server).get('/test').expect(200);
+        });
     });
 
-    describe('in test mode', () => {
-        // This one checks that `servers` section gets overwritten
-        // If `servers` is not overwritten, the URL won't match the base URL constraint
-        it('will validate all requests', async (): Promise<unknown> => {
+    describe('With installOpenApiValidator', function () {
+        it('will not run security handlers', async function (): Promise<unknown> {
             const server = await buildServer(true, 'test');
-            return request(server)
-                .get('/test')
-                .expect(400)
-                .expect(/\/query\/s/u);
+            return request(server).get('/auth').expect(204);
         });
 
-        it('will thoroughly validate requests', async (): Promise<unknown> => {
-            const server = await buildServer(true, 'test');
-            return request(server)
-                .get('/test?s=2012-13-31')
-                .expect(400)
-                .expect(/\/query\/s/u)
-                .expect(/must match format/u);
-        });
+        describe('in test mode', function () {
+            // This one checks that `servers` section gets overwritten
+            // If `servers` is not overwritten, the URL won't match the base URL constraint
+            it('will validate all requests', async function (): Promise<unknown> {
+                const server = await buildServer(true, 'test');
+                return request(server)
+                    .get('/test')
+                    .expect(400)
+                    .expect(/\/query\/s/u);
+            });
 
-        it('will validate responses', async (): Promise<unknown> => {
-            const server = await buildServer(true, 'test');
-            return request(server)
-                .get('/test?s=2012-12-31')
-                .expect(500)
-                .expect(/\/response\/debug/u);
-        });
-    });
+            it('will thoroughly validate requests', async function (): Promise<unknown> {
+                const server = await buildServer(true, 'test');
+                return request(server)
+                    .get('/test?s=2012-13-31')
+                    .expect(400)
+                    .expect(/\/query\/s/u)
+                    .expect(/must match format/u);
+            });
 
-    describe('in production mode', () => {
-        it('will validate all requests', async (): Promise<unknown> => {
-            const server = await buildServer(true, 'production');
-            return request(server)
-                .get('/test')
-                .expect(400)
-                .expect(/\/query\/s/u);
+            it('will validate responses', async function (): Promise<unknown> {
+                const server = await buildServer(true, 'test');
+                return request(server)
+                    .get('/test?s=2012-12-31')
+                    .expect(500)
+                    .expect(/\/response\/debug/u);
+            });
         });
 
-        it('will not thoroughly validate requests', async (): Promise<unknown> => {
-            const server = await buildServer(true, 'production');
-            return request(server).get('/test?s=2012-13-31').expect(200);
+        describe('in production mode', function () {
+            it('will validate all requests', async function (): Promise<unknown> {
+                const server = await buildServer(true, 'production');
+                return request(server)
+                    .get('/test')
+                    .expect(400)
+                    .expect(/\/query\/s/u);
+            });
+
+            it('will not thoroughly validate requests', async function (): Promise<unknown> {
+                const server = await buildServer(true, 'production');
+                return request(server).get('/test?s=2012-13-31').expect(200);
+            });
+
+            it('will not validate responses', async function (): Promise<unknown> {
+                const server = await buildServer(true, 'production');
+                return request(server).get('/test?s=2012-12-31').expect(200);
+            });
         });
+    });
+
+    describe('OpenAPI 3.1', function () {
+        it('should load the spec', function () {
+            const app = express();
+            const promise = installOpenApiValidator(
+                join(dirname(fileURLToPath(import.meta.url)), 'openapi-3.1.yaml'),
+                app,
+                'development',
+            );
 
-        it('will not validate responses', async (): Promise<unknown> => {
-            const server = await buildServer(true, 'production');
-            return request(server).get('/test?s=2012-12-31').expect(200);
+            return doesNotReject(promise);
         });
     });
 });