refactor(helpers): reorganize OpenAPI predicates into separate module

Refs #2717

src/execute/index.js

@@ -9,7 +9,8 @@ import SWAGGER2_PARAMETER_BUILDERS from './swagger2/parameter-builders.js';
 import * as OAS3_PARAMETER_BUILDERS from './oas3/parameter-builders.js';
 import oas3BuildRequest from './oas3/build-request.js';
 import swagger2BuildRequest from './swagger2/build-request.js';
-import { getOperationRaw, legacyIdFromPathMethod, isOAS3 } from '../helpers/index.js';
+import { getOperationRaw, legacyIdFromPathMethod } from '../helpers/index.js';
+import { isOpenAPI3 } from '../helpers/openapi-predicates.js';
 
 const arrayOrEmpty = (ar) => (Array.isArray(ar) ? ar : []);
 
@@ -103,7 +104,7 @@ export function buildRequest(options) {
 
   let { parameters, parameterBuilders } = options;
 
-  const specIsOAS3 = isOAS3(spec);
+  const specIsOAS3 = isOpenAPI3(spec);
   if (!parameterBuilders) {
     // user did not provide custom parameter builders
     if (specIsOAS3) {
@@ -283,7 +284,7 @@ const stripNonAlpha = (str) => (str ? str.replace(/\W/g, '') : null);
 
 // be careful when modifying this! it is a publicly-exposed method.
 export function baseUrl(obj) {
-  const specIsOAS3 = isOAS3(obj.spec);
+  const specIsOAS3 = isOpenAPI3(obj.spec);
 
   return specIsOAS3 ? oas3BaseUrl(obj) : swagger2BaseUrl(obj);
 }

src/helpers/index.js

@@ -1,25 +1,6 @@
 const toLower = (str) => String.prototype.toLowerCase.call(str);
 const escapeString = (str) => str.replace(/[^\w]/gi, '_');
 
-// Spec version detection
-export function isOAS3(spec) {
-  const oasVersion = spec.openapi;
-  if (!oasVersion) {
-    return false;
-  }
-
-  return oasVersion.startsWith('3');
-}
-
-export function isSwagger2(spec) {
-  const swaggerVersion = spec.swagger;
-  if (!swaggerVersion) {
-    return false;
-  }
-
-  return swaggerVersion.startsWith('2');
-}
-
 // Strategy for determining operationId
 export function opId(operation, pathName, method = '', { v2OperationIdCompatibilityMode } = {}) {
   if (!operation || typeof operation !== 'object') {

src/helpers/openapi-predicates.js

@@ -0,0 +1,30 @@
+export const isOpenAPI2 = (spec) => {
+  try {
+    const { swagger } = spec;
+    return swagger === '2.0';
+  } catch {
+    return false;
+  }
+};
+export const isOpenAPI30 = (spec) => {
+  try {
+    const { openapi } = spec;
+    return typeof openapi === 'string' && openapi.startsWith('3.0');
+  } catch {
+    return false;
+  }
+};
+
+export const isOpenAPI31 = (spec) => {
+  try {
+    const { openapi } = spec;
+    return typeof openapi === 'string' && openapi.startsWith('3.1');
+  } catch {
+    return false;
+  }
+};
+
+export const isOpenAPI3 = (spec) => isOpenAPI30(spec) || isOpenAPI31(spec);
+
+// backward compatibility export
+export { isOpenAPI2 as isSwagger2 };

test/helpers/openapi-predicates.js

@@ -0,0 +1,103 @@
+import {
+  isOpenAPI30,
+  isOpenAPI31,
+  isOpenAPI3,
+  isOpenAPI2,
+  isSwagger2,
+} from '../../src/helpers/openapi-predicates.js';
+
+describe('helpers - OpenAPI predicates', () => {
+  describe('isOpenAPI30', () => {
+    test('should detect OpenAPI 3.0.x versions', () => {
+      expect(isOpenAPI30({ openapi: '3.0.0' })).toBe(true);
+      expect(isOpenAPI30({ openapi: '3.0.1' })).toBe(true);
+      expect(isOpenAPI30({ openapi: '3.0.2' })).toBe(true);
+      expect(isOpenAPI30({ openapi: '3.0.3' })).toBe(true);
+    });
+
+    test('should reject other OpenAPI versions', () => {
+      expect(isOpenAPI30({ openapi: '3.1.0' })).toBe(false);
+      expect(isOpenAPI30({ swagger: '2.0' })).toBe(false);
+    });
+
+    test('should reject values that are not OpenAPI spec', () => {
+      expect(isOpenAPI30(null)).toBe(false);
+      expect(isOpenAPI30(undefined)).toBe(false);
+      expect(isOpenAPI30({})).toBe(false);
+    });
+  });
+
+  describe('isOpenAPI31', () => {
+    test('should detect OpenAPI 3.1.x versions', () => {
+      expect(isOpenAPI31({ openapi: '3.1.0' })).toBe(true);
+      expect(isOpenAPI31({ openapi: '3.1.1' })).toBe(true);
+    });
+
+    test('should reject other OpenAPI versions', () => {
+      expect(isOpenAPI31({ openapi: '3.0.0' })).toBe(false);
+      expect(isOpenAPI31({ swagger: '2.0' })).toBe(false);
+    });
+
+    test('should reject values that are not OpenAPI spec', () => {
+      expect(isOpenAPI31(null)).toBe(false);
+      expect(isOpenAPI31(undefined)).toBe(false);
+      expect(isOpenAPI31({})).toBe(false);
+    });
+  });
+
+  describe('isOpenAPI3', () => {
+    test('should detect OpenAPI 3.x.y versions', () => {
+      expect(isOpenAPI3({ openapi: '3.0.0' })).toBe(true);
+      expect(isOpenAPI3({ openapi: '3.0.1' })).toBe(true);
+      expect(isOpenAPI3({ openapi: '3.0.2' })).toBe(true);
+      expect(isOpenAPI3({ openapi: '3.0.3' })).toBe(true);
+      expect(isOpenAPI3({ openapi: '3.1.0' })).toBe(true);
+      expect(isOpenAPI3({ openapi: '3.1.1' })).toBe(true);
+    });
+
+    test('should reject other OpenAPI versions', () => {
+      expect(isOpenAPI3({ openapi: '3.2.0' })).toBe(false);
+      expect(isOpenAPI3({ swagger: '2.0' })).toBe(false);
+    });
+
+    test('should reject values that are not OpenAPI spec', () => {
+      expect(isOpenAPI3(null)).toBe(false);
+      expect(isOpenAPI3(undefined)).toBe(false);
+      expect(isOpenAPI3({})).toBe(false);
+    });
+  });
+
+  describe('isOpenAPI2', () => {
+    test('should detect OpenAPI 2.0 versions', () => {
+      expect(isOpenAPI2({ swagger: '2.0' })).toBe(true);
+    });
+
+    test('should reject other OpenAPI versions', () => {
+      expect(isOpenAPI2({ openapi: '3.0.0' })).toBe(false);
+      expect(isOpenAPI2({ openapi: '3.1.0' })).toBe(false);
+    });
+
+    test('should reject values that are not OpenAPI spec', () => {
+      expect(isOpenAPI2(null)).toBe(false);
+      expect(isOpenAPI2(undefined)).toBe(false);
+      expect(isOpenAPI2({})).toBe(false);
+    });
+
+    describe('should be aliased by isSwagger2', () => {
+      test('should detect OpenAPI 2.0 versions', () => {
+        expect(isSwagger2({ swagger: '2.0' })).toBe(true);
+      });
+
+      test('should reject other OpenAPI versions', () => {
+        expect(isSwagger2({ openapi: '3.0.0' })).toBe(false);
+        expect(isSwagger2({ openapi: '3.1.0' })).toBe(false);
+      });
+
+      test('should reject values that are not OpenAPI spec', () => {
+        expect(isSwagger2(null)).toBe(false);
+        expect(isSwagger2(undefined)).toBe(false);
+        expect(isSwagger2({})).toBe(false);
+      });
+    });
+  });
+});