feat(reference): add OpenAPI 2.0 dereference strategy (#3435)

Refs #3102

Author: char0n

packages/apidom-ns-json-schema-draft-4/src/refractor/predicates.ts

@@ -1,7 +1,12 @@
-import { isObjectElement, Element } from '@swagger-api/apidom-core';
+import { isObjectElement, ObjectElement } from '@swagger-api/apidom-core';
+
+export interface JSONReferenceLikeElement extends ObjectElement {
+  hasKey: (value: '$ref') => true;
+}
 
 // eslint-disable-next-line import/prefer-default-export
-export const isJSONReferenceLikeElement = <T extends Element>(element: T): boolean => {
-  // @ts-ignore
+export const isJSONReferenceLikeElement = (
+  element: unknown,
+): element is JSONReferenceLikeElement => {
   return isObjectElement(element) && element.hasKey('$ref');
 };

packages/apidom-ns-openapi-2/src/index.ts

@@ -12,6 +12,7 @@ export {
 } from '@swagger-api/apidom-core';
 export {
   isJSONReferenceElement,
+  isJSONReferenceLikeElement,
   JSONReferenceElement,
 } from '@swagger-api/apidom-ns-json-schema-draft-4';
 
@@ -33,6 +34,7 @@ export {
   isLicenseElement,
   isPathsElement,
   isPathItemElement,
+  isPathItemElementExternal,
   isOperationElement,
   isExternalDocumentationElement,
   isParameterElement,
@@ -44,7 +46,9 @@ export {
   isHeaderElement,
   isTagElement,
   isReferenceElement,
+  isReferenceElementExternal,
   isSchemaElement,
+  isJSONReferenceElementExternal,
   isXmlElement,
   isDefinitionsElement,
   isParametersDefinitionsElement,

packages/apidom-ns-openapi-2/src/predicates.ts

@@ -1,4 +1,13 @@
-import { createPredicate } from '@swagger-api/apidom-core';
+import {
+  createPredicate,
+  ElementPredicate,
+  isStringElement,
+  toValue,
+} from '@swagger-api/apidom-core';
+import {
+  isJSONReferenceElement,
+  JSONReferenceElement,
+} from '@swagger-api/apidom-ns-json-schema-draft-4';
 
 import SwaggerElement from './elements/Swagger';
 import SwaggerVersionElement from './elements/SwaggerVersion';
@@ -98,6 +107,21 @@ export const isPathItemElement = createPredicate(
   },
 );
 
+export const isPathItemElementExternal: ElementPredicate<PathItemElement> = (
+  element: unknown,
+): element is PathItemElement => {
+  if (!isPathItemElement(element)) {
+    return false;
+  }
+  if (!isStringElement(element.$ref)) {
+    return false;
+  }
+
+  const value = toValue(element.$ref);
+
+  return typeof value === 'string' && value.length > 0 && !value.startsWith('#');
+};
+
 export const isOperationElement = createPredicate(
   ({ hasBasicElementProps, isElementType, primitiveEq }) => {
     return (element: unknown): element is OperationElement =>
@@ -208,6 +232,21 @@ export const isReferenceElement = createPredicate(
   },
 );
 
+export const isReferenceElementExternal: ElementPredicate<ReferenceElement> = (
+  element: unknown,
+): element is ReferenceElement => {
+  if (!isReferenceElement(element)) {
+    return false;
+  }
+  if (!isStringElement(element.$ref)) {
+    return false;
+  }
+
+  const value = toValue(element.$ref);
+
+  return typeof value === 'string' && value.length > 0 && !value.startsWith('#');
+};
+
 export const isSchemaElement = createPredicate(
   ({ hasBasicElementProps, isElementType, primitiveEq }) => {
     return (element: unknown): element is SchemaElement =>
@@ -218,6 +257,21 @@ export const isSchemaElement = createPredicate(
   },
 );
 
+export const isJSONReferenceElementExternal: ElementPredicate<JSONReferenceElement> = (
+  element: unknown,
+): element is PathItemElement => {
+  if (!isJSONReferenceElement(element)) {
+    return false;
+  }
+  if (!isStringElement(element.$ref)) {
+    return false;
+  }
+
+  const value = toValue(element.$ref);
+
+  return typeof value === 'string' && value.length > 0 && !value.startsWith('#');
+};
+
 export const isXmlElement = createPredicate(
   ({ hasBasicElementProps, isElementType, primitiveEq }) => {
     return (element: unknown): element is XmlElement =>

packages/apidom-reference/README.md

@@ -1099,9 +1099,9 @@ It's possible to **change** strategies **order globally** by mutating global `re
 
 ```js
 import { options } from '@swagger-api/apidom-reference';
-import { AsyncApi2ResolveStrategy } from '@swagger-api/apidom-reference/resolve/strategies/asyncapi-2';
-import { OpenApi3_0ResolveStrategy } from '@swagger-api/apidom-reference/resolve/strategies/openapi-3-0';
-import { OpenApi3_1ResolveStrategy } from '@swagger-api/apidom-reference/resolve/strategies/openapi-3-1';
+import AsyncApi2ResolveStrategy from '@swagger-api/apidom-reference/resolve/strategies/asyncapi-2';
+import OpenApi3_0ResolveStrategy from '@swagger-api/apidom-reference/resolve/strategies/openapi-3-0';
+import OpenApi3_1ResolveStrategy from '@swagger-api/apidom-reference/resolve/strategies/openapi-3-1';
 
 options.resolve.strategies = [
   OpenApi3_0ResolveStrategy(),
@@ -1114,9 +1114,9 @@ To **change** the strategies **order** on ad-hoc basis:
 
 ```js
 import { resolve } from '@swagger-api/apidom-reference';
-import { AsyncApi2ResolveStrategy } from '@swagger-api/apidom-reference/resolve/strategies/asyncapi-2';
-import { OpenApi3_0ResolveStrategy } from '@swagger-api/apidom-reference/resolve/strategies/openapi-3-0';
-import { OpenApi3_1ResolveStrategy } from '@swagger-api/apidom-reference/resolve/strategies/openapi-3-1';
+import AsyncApi2ResolveStrategy from '@swagger-api/apidom-reference/resolve/strategies/asyncapi-2';
+import OpenApi3_0ResolveStrategy from '@swagger-api/apidom-reference/resolve/strategies/openapi-3-0';
+import OpenApi3_1ResolveStrategy from '@swagger-api/apidom-reference/resolve/strategies/openapi-3-1';
 
 
 await resolve('/home/user/oas.json', {
@@ -1361,6 +1361,20 @@ Supported media types:
 ]
 ```
 
+##### [openapi-2](https://github.com/swagger-api/apidom/tree/main/packages/apidom-reference/src/dereference/strategies/openapi-2)
+
+Dereference strategy for dereferencing [OpenApi 2.0](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/2.0.md) definitions.
+
+Supported media types:
+
+```js
+[
+  'application/vnd.oai.openapi;version=2.0',
+  'application/vnd.oai.openapi+json;version=2.0',
+  'application/vnd.oai.openapi+yaml;version=2.0',
+]
+```
+
 ##### [openapi-3-0](https://github.com/swagger-api/apidom/tree/main/packages/apidom-reference/src/dereference/strategies/openapi-3-0)
 
 Dereference strategy for dereferencing [OpenApi 3.0.x](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.0.3.md) definitions.
@@ -1410,6 +1424,7 @@ returns `true` or until entire list of strategies is exhausted (throws error).
 
 ```js
 [
+  OpenApi2DereferenceStrategy(),
   OpenApi3_0DereferenceStrategy(),
   OpenApi3_1DereferenceStrategy(),
   AsyncApi2DereferenceStrategy(),
@@ -1421,11 +1436,13 @@ It's possible to **change** strategies **order globally** by mutating global `de
 
 ```js
 import { options } from '@swagger-api/apidom-reference';
-import { AsyncApi2DereferenceStrategy } from '@swagger-api/apidom-reference/dereference/strategies/asyncapi-2'
-import { OpenApi3_0DereferenceStrategy } from '@swagger-api/apidom-reference/dereference/strategies/openapi-3-0'
-import { OpenApi3_1DereferenceStrategy } from '@swagger-api/apidom-reference/dereference/strategies/openapi-3-1'
+import AsyncApi2DereferenceStrategy from '@swagger-api/apidom-reference/dereference/strategies/asyncapi-2'
+import OpenApi2DereferenceStrategy from '@swagger-api/apidom-reference/dereference/strategies/openapi-2'
+import OpenApi3_0DereferenceStrategy from '@swagger-api/apidom-reference/dereference/strategies/openapi-3-0'
+import OpenApi3_1DereferenceStrategy from '@swagger-api/apidom-reference/dereference/strategies/openapi-3-1'
 
 options.dereference.strategies = [
+  OpenApi2DereferenceStrategy(),
   OpenApi3_0DereferenceStrategy(),
   OpenApi3_1DereferenceStrategy(),
   AsyncApi2DereferenceStrategy(),
@@ -1436,9 +1453,10 @@ To **change** the strategies **order** on ad-hoc basis:
 
 ```js
 import { dereference } from '@swagger-api/apidom-reference';
-import { AsyncApi2DereferenceStrategy } from '@swagger-api/apidom-reference/dereference/strategies/asyncapi-2'
-import { OpenApi3_0DereferenceStrategy } from '@swagger-api/apidom-reference/dereference/strategies/openapi-3-0'
-import { OpenApi3_1DereferenceStrategy } from '@swagger-api/apidom-reference/dereference/strategies/openapi-3-1'
+import AsyncApi2DereferenceStrategy from '@swagger-api/apidom-reference/dereference/strategies/asyncapi-2'
+import OpenApi2DereferenceStrategy from '@swagger-api/apidom-reference/dereference/strategies/openapi-2'
+import OpenApi3_0DereferenceStrategy from '@swagger-api/apidom-reference/dereference/strategies/openapi-3-0'
+import OpenApi3_1DereferenceStrategy from '@swagger-api/apidom-reference/dereference/strategies/openapi-3-1'
 
 await dereference('/home/user/oas.json', {
   parse: {
@@ -1447,6 +1465,7 @@ await dereference('/home/user/oas.json', {
   dereference: {
     strategies: [
       AsyncApi2DereferenceStrategy(),
+      OpenApi2DereferenceStrategy(),
       OpenApi3_0DereferenceStrategy(),
       OpenApi3_1DereferenceStrategy(),
     ]

packages/apidom-reference/package.json

@@ -145,6 +145,11 @@
       "require": "./cjs/dereference/strategies/asyncapi-2/index.cjs",
       "types": "./types/dereference/strategies/asyncapi-2/index.d.ts"
     },
+    "./dereference/strategies/openapi-2": {
+      "import": "./es/dereference/strategies/openapi-2/index.mjs",
+      "require": "./cjs/dereference/strategies/openapi-2/index.cjs",
+      "types": "./types/dereference/strategies/openapi-2/index.d.ts"
+    },
     "./dereference/strategies/openapi-3-0": {
       "import": "./es/dereference/strategies/openapi-3-0/index.mjs",
       "require": "./cjs/dereference/strategies/openapi-3-0/index.cjs",

packages/apidom-reference/src/configuration/saturated.ts

@@ -16,6 +16,7 @@ import AsyncApiYaml2Parser from '../parse/parsers/asyncapi-yaml-2';
 import JsonParser from '../parse/parsers/json';
 import YamlParser from '../parse/parsers/yaml-1-2';
 import BinaryParser from '../parse/parsers/binary/index-node';
+import OpenApi2DereferenceStrategy from '../dereference/strategies/openapi-2';
 import OpenApi3_0DereferenceStrategy from '../dereference/strategies/openapi-3-0';
 import OpenApi3_1DereferenceStrategy from '../dereference/strategies/openapi-3-1';
 import AsyncApi2DereferenceStrategy from '../dereference/strategies/asyncapi-2';
@@ -49,6 +50,7 @@ options.resolve.strategies = [
 ];
 
 options.dereference.strategies = [
+  OpenApi2DereferenceStrategy(),
   OpenApi3_0DereferenceStrategy(),
   OpenApi3_1DereferenceStrategy(),
   AsyncApi2DereferenceStrategy(),

packages/apidom-reference/src/dereference/strategies/openapi-2/index.ts

@@ -0,0 +1,74 @@
+import stampit from 'stampit';
+import { defaultTo, propEq } from 'ramda';
+import { createNamespace, visit, Element } from '@swagger-api/apidom-core';
+import openApi2Namespace, {
+  getNodeType,
+  isSwaggerElement,
+  keyMap,
+  mediaTypes,
+} from '@swagger-api/apidom-ns-openapi-2';
+
+import DereferenceStrategy from '../DereferenceStrategy';
+import {
+  DereferenceStrategy as IDereferenceStrategy,
+  File as IFile,
+  ReferenceOptions as IReferenceOptions,
+} from '../../../types';
+import Reference from '../../../Reference';
+import ReferenceSet from '../../../ReferenceSet';
+import OpenApi2DereferenceVisitor from './visitor';
+
+// @ts-ignore
+const visitAsync = visit[Symbol.for('nodejs.util.promisify.custom')];
+
+const OpenApi2DereferenceStrategy: stampit.Stamp<IDereferenceStrategy> = stampit(
+  DereferenceStrategy,
+  {
+    init() {
+      this.name = 'openapi-2';
+    },
+    methods: {
+      canDereference(file: IFile): boolean {
+        // assert by media type
+        if (file.mediaType !== 'text/plain') {
+          return mediaTypes.includes(file.mediaType);
+        }
+
+        // assert by inspecting ApiDOM
+        return isSwaggerElement(file.parseResult?.api);
+      },
+
+      async dereference(file: IFile, options: IReferenceOptions): Promise<Element> {
+        const namespace = createNamespace(openApi2Namespace);
+        const refSet = defaultTo(ReferenceSet(), options.dereference.refSet);
+        let reference;
+
+        if (!refSet.has(file.uri)) {
+          reference = Reference({ uri: file.uri, value: file.parseResult });
+          refSet.add(reference);
+        } else {
+          // pre-computed refSet was provided as configuration option
+          reference = refSet.find(propEq(file.uri, 'uri'));
+        }
+
+        const visitor = OpenApi2DereferenceVisitor({ reference, namespace, options });
+        const dereferencedElement = await visitAsync(refSet.rootRef.value, visitor, {
+          keyMap,
+          nodeTypeGetter: getNodeType,
+        });
+
+        /**
+         * Release all memory if this refSet was not provided as an configuration option.
+         * If provided as configuration option, then provider is responsible for cleanup.
+         */
+        if (options.dereference.refSet === null) {
+          refSet.clean();
+        }
+
+        return dereferencedElement;
+      },
+    },
+  },
+);
+
+export default OpenApi2DereferenceStrategy;