feat(reference): add OAS 3.1 Example.externalValue dereference

Refs #467

apidom/packages/apidom-ns-openapi-3-1/src/elements/Example.ts

@@ -1,4 +1,5 @@
-import { Attributes, Meta, ObjectElement, StringElement } from 'minim';
+import { Attributes, Meta, Element } from 'minim';
+import { ObjectElement, StringElement } from 'apidom';
 
 class Example extends ObjectElement {
   constructor(content?: Record<string, unknown>, meta?: Meta, attributes?: Attributes) {
@@ -22,11 +23,11 @@ class Example extends ObjectElement {
     this.set('description', description);
   }
 
-  get value(): StringElement {
+  get value(): Element {
     return this.get('value');
   }
 
-  set value(value: StringElement) {
+  set value(value: Element) {
     this.set('value', value);
   }
 

apidom/packages/apidom-ns-openapi-3-1/src/index.ts

@@ -19,6 +19,7 @@ export {
   isCallbackElement,
   isComponentsElement,
   isContactElement,
+  isExampleElement,
   isExternalDocumentationElement,
   isInfoElement,
   isJsonSchemaDialectElement,

apidom/packages/apidom-ns-openapi-3-1/src/predicates.ts

@@ -5,6 +5,7 @@ import { createPredicate, isStringElement } from 'apidom';
 import CallbackElement from './elements/Callback';
 import ComponentsElement from './elements/Components';
 import ContactElement from './elements/Contact';
+import ExampleElement from './elements/Example';
 import ExternalDocumentationElement from './elements/ExternalDocumentation';
 import HeaderElement from './elements/Header';
 import InfoElement from './elements/Info';
@@ -63,6 +64,18 @@ export const isContactElement = createPredicate(
   },
 );
 
+export const isExampleElement = createPredicate(
+  ({ hasBasicElementProps, isElementType, primitiveEq }) => {
+    const isElementTypeExample = isElementType('example');
+    const primitiveEqObject = primitiveEq('object');
+
+    return either(
+      is(ExampleElement),
+      allPass([hasBasicElementProps, isElementTypeExample, primitiveEqObject]),
+    );
+  },
+);
+
 export const isExternalDocumentationElement = createPredicate(
   ({ hasBasicElementProps, isElementType, primitiveEq }) => {
     const isElementTypeExternalDocumentation = isElementType('externalDocumentation');

apidom/packages/apidom-reference/src/dereference/strategies/openapi-3-1/visitor.ts

@@ -10,6 +10,7 @@ import {
   PathItemElement,
   LinkElement,
   OperationElement,
+  ExampleElement,
   SchemaElement,
   isReferenceElementExternal,
   isPathItemElementExternal,
@@ -253,9 +254,9 @@ const OpenApi3_1DereferenceVisitor = stampit({
         return undefined;
       }
 
-      // operationRef and operationId are mutually exclusive
+      // operationRef and operationId fields are mutually exclusive
       if (isStringElement(linkElement.operationRef) && isStringElement(linkElement.operationId)) {
-        throw new Error('LinkElement operationRef and operationId are mutually exclusive.');
+        throw new Error('LinkElement operationRef and operationId fields are mutually exclusive.');
       }
 
       // @ts-ignore
@@ -288,6 +289,30 @@ const OpenApi3_1DereferenceVisitor = stampit({
       return undefined;
     },
 
+    async ExampleElement(exampleElement: ExampleElement) {
+      // ignore ExampleElement without externalValue field
+      if (!isStringElement(exampleElement.externalValue)) {
+        return undefined;
+      }
+
+      // ignore resolving ExampleElement externalValue
+      if (!this.options.resolve.external && isStringElement(exampleElement.externalValue)) {
+        return undefined;
+      }
+
+      // value and externalValue fields are mutually exclusive
+      if (exampleElement.hasKey('value') && isStringElement(exampleElement.externalValue)) {
+        throw new Error('ExampleElement value and externalValue fields are mutually exclusive.');
+      }
+
+      const reference = await this.toReference(exampleElement.externalValue.toValue());
+
+      // eslint-disable-next-line no-param-reassign
+      exampleElement.value = reference.value.result;
+
+      return undefined;
+    },
+
     async SchemaElement(referencingElement: SchemaElement) {
       /**
        * Skip traversal for already visited schemas and all their child schemas.

apidom/packages/apidom-reference/test/dereference/strategies/openapi-3-1/example-object/fixtures/external-value-binary/root.json

@@ -0,0 +1,11 @@
+{
+  "openapi": "3.1.0",
+  "components": {
+    "examples": {
+      "example1": {
+        "description": "example1 description",
+        "externalValue": "./favicon.ico"
+      }
+    }
+  }
+}

apidom/packages/apidom-reference/test/dereference/strategies/openapi-3-1/example-object/fixtures/external-value-ignore-external/dereferenced.json

@@ -0,0 +1,13 @@
+[
+  {
+    "openapi": "3.1.0",
+    "components": {
+      "examples": {
+        "example1": {
+          "description": "example1 description",
+          "externalValue": "./ex.json"
+        }
+      }
+    }
+  }
+]

apidom/packages/apidom-reference/test/dereference/strategies/openapi-3-1/example-object/fixtures/external-value-ignore-external/ex.json

@@ -0,0 +1 @@
+{}

apidom/packages/apidom-reference/test/dereference/strategies/openapi-3-1/example-object/fixtures/external-value-ignore-external/root.json

@@ -0,0 +1,11 @@
+{
+  "openapi": "3.1.0",
+  "components": {
+    "examples": {
+      "example1": {
+        "description": "example1 description",
+        "externalValue": "./ex.json"
+      }
+    }
+  }
+}

apidom/packages/apidom-reference/test/dereference/strategies/openapi-3-1/example-object/fixtures/external-value-json/dereferenced.json

@@ -0,0 +1,17 @@
+[
+  {
+    "openapi": "3.1.0",
+    "components": {
+      "examples": {
+        "example1": {
+          "description": "example1 description",
+          "value": {
+            "prop1": "value1",
+            "prop2": "value2"
+          },
+          "externalValue": "./ex.json"
+        }
+      }
+    }
+  }
+]

apidom/packages/apidom-reference/test/dereference/strategies/openapi-3-1/example-object/fixtures/external-value-json/ex.json

@@ -0,0 +1,4 @@
+{
+  "prop1": "value1",
+  "prop2": "value2"
+}

apidom/packages/apidom-reference/test/dereference/strategies/openapi-3-1/example-object/fixtures/external-value-json/root.json

@@ -0,0 +1,11 @@
+{
+  "openapi": "3.1.0",
+  "components": {
+    "examples": {
+      "example1": {
+        "description": "example1 description",
+        "externalValue": "./ex.json"
+      }
+    }
+  }
+}

apidom/packages/apidom-reference/test/dereference/strategies/openapi-3-1/example-object/fixtures/external-value-pointer/dereferenced.json

@@ -0,0 +1,17 @@
+[
+  {
+    "openapi": "3.1.0",
+    "components": {
+      "examples": {
+        "example1": {
+          "description": "example1 description",
+          "value": {
+            "prop1": "value1",
+            "prop2": "value2"
+          },
+          "externalValue": "./ex.json#/json/pointer"
+        }
+      }
+    }
+  }
+]

apidom/packages/apidom-reference/test/dereference/strategies/openapi-3-1/example-object/fixtures/external-value-pointer/ex.json

@@ -0,0 +1,4 @@
+{
+  "prop1": "value1",
+  "prop2": "value2"
+}

apidom/packages/apidom-reference/test/dereference/strategies/openapi-3-1/example-object/fixtures/external-value-pointer/root.json

@@ -0,0 +1,11 @@
+{
+  "openapi": "3.1.0",
+  "components": {
+    "examples": {
+      "example1": {
+        "description": "example1 description",
+        "externalValue": "./ex.json#/json/pointer"
+      }
+    }
+  }
+}

apidom/packages/apidom-reference/test/dereference/strategies/openapi-3-1/example-object/fixtures/external-value-text/dereferenced.json

@@ -0,0 +1,14 @@
+[
+  {
+    "openapi": "3.1.0",
+    "components": {
+      "examples": {
+        "example1": {
+          "description": "example1 description",
+          "value": "dmFsMTt2YWwyO3ZhbDMK",
+          "externalValue": "./ex.csv"
+        }
+      }
+    }
+  }
+]

apidom/packages/apidom-reference/test/dereference/strategies/openapi-3-1/example-object/fixtures/external-value-text/ex.csv

@@ -0,0 +1 @@
+val1;val2;val3

apidom/packages/apidom-reference/test/dereference/strategies/openapi-3-1/example-object/fixtures/external-value-text/root.json

@@ -0,0 +1,11 @@
+{
+  "openapi": "3.1.0",
+  "components": {
+    "examples": {
+      "example1": {
+        "description": "example1 description",
+        "externalValue": "./ex.csv"
+      }
+    }
+  }
+}

apidom/packages/apidom-reference/test/dereference/strategies/openapi-3-1/example-object/fixtures/external-value-unresolvable/root.json

@@ -0,0 +1,11 @@
+{
+  "openapi": "3.1.0",
+  "components": {
+    "examples": {
+      "example1": {
+        "description": "example1 description",
+        "externalValue": "./ex.json"
+      }
+    }
+  }
+}

apidom/packages/apidom-reference/test/dereference/strategies/openapi-3-1/example-object/fixtures/external-value-value-both-defined/ex.json

@@ -0,0 +1 @@
+{}

apidom/packages/apidom-reference/test/dereference/strategies/openapi-3-1/example-object/fixtures/external-value-value-both-defined/root.json

@@ -0,0 +1,12 @@
+{
+  "openapi": "3.1.0",
+  "components": {
+    "examples": {
+      "example1": {
+        "description": "example1 description",
+        "value": "sample value",
+        "externalValue": "./ex.json"
+      }
+    }
+  }
+}

apidom/packages/apidom-reference/test/dereference/strategies/openapi-3-1/example-object/fixtures/external-value-yaml/dereferenced.json

@@ -0,0 +1,17 @@
+[
+  {
+    "openapi": "3.1.0",
+    "components": {
+      "examples": {
+        "example1": {
+          "description": "example1 description",
+          "value": {
+            "prop1": "value1",
+            "prop2": "value2"
+          },
+          "externalValue": "./ex.yaml"
+        }
+      }
+    }
+  }
+]

apidom/packages/apidom-reference/test/dereference/strategies/openapi-3-1/example-object/fixtures/external-value-yaml/ex.yaml

@@ -0,0 +1,3 @@
+---
+prop1: value1
+prop2: value2

apidom/packages/apidom-reference/test/dereference/strategies/openapi-3-1/example-object/fixtures/external-value-yaml/root.json

@@ -0,0 +1,11 @@
+{
+  "openapi": "3.1.0",
+  "components": {
+    "examples": {
+      "example1": {
+        "description": "example1 description",
+        "externalValue": "./ex.yaml"
+      }
+    }
+  }
+}