feat(resolver): collect errors in ExampleElement visitor hook

This change in specific to OpenAPI 3.1.0 resolution strategy. Errors are now collected, instead of thrown and visitor tranversal is not interrupted. Refs #2798
swagger-api · Jan 30, 2023 · f4928f0 · f4928f0
1 parent f038e0e
commit f4928f0
Show file tree

Hide file tree

Showing 7 changed files with 140 additions and 15 deletions.
diff --git a/src/helpers/apidom/reference/dereference/strategies/openapi-3-1-swagger-client/index.js b/src/helpers/apidom/reference/dereference/strategies/openapi-3-1-swagger-client/index.js
@@ -53,6 +53,7 @@ const OpenApi3_1SwaggerClientDereferenceStrategy = OpenApi3_1DereferenceStrategy
         reference,
         namespace,
         options,
+        errors: options.dereference.dereferenceOpts?.errors ?? [],
         useCircularStructures: this.useCircularStructures,
         allowMetaPatches: this.allowMetaPatches,
       });

diff --git a/...pidom/reference/dereference/strategies/openapi-3-1-swagger-client/utils/get-root-cause.js b/...pidom/reference/dereference/strategies/openapi-3-1-swagger-client/utils/get-root-cause.js
@@ -0,0 +1,17 @@
+/**
+ * Retrieves the root cause of ApiDOM error hierarchy.
+ * ApiDOM error hierarchies are modeled similar to Java.
+ * Every error can have cause attribute which references
+ * cause of this error.
+ */
+const getRootCause = (error) => {
+  if (!Object.hasOwn(error, 'cause')) return error;
+
+  let { cause } = error;
+  while (Object.hasOwn(cause, 'cause')) {
+    cause = cause.cause;
+  }
+  return cause;
+};
+
+export default getRootCause;
diff --git a/...pidom/reference/dereference/strategies/openapi-3-1-swagger-client/visitors/dereference.js b/...pidom/reference/dereference/strategies/openapi-3-1-swagger-client/visitors/dereference.js
@@ -38,19 +38,30 @@ import {
   EvaluationJsonSchemaUriError,
 } from '@swagger-api/apidom-reference/dereference/strategies/openapi-3-1/selectors/uri';
 
+import toPath from '../utils/to-path.js';
+import getRootCause from '../utils/get-root-cause.js';
+import specMapMod from '../../../../../../../specmap/lib/refs.js';
+
+const { wrapError } = specMapMod;
 const visitAsync = visit[Symbol.for('nodejs.util.promisify.custom')];
 
 const OpenApi3_1SwaggerClientDereferenceVisitor = OpenApi3_1DereferenceVisitor.compose({
   props: {
     useCircularStructures: true,
     allowMetaPatches: false,
+    errors: [],
+    basePath: null,
   },
   init({
     allowMetaPatches = this.allowMetaPatches,
     useCircularStructures = this.useCircularStructures,
+    errors = this.errors,
+    basePath = this.basePath,
   }) {
     this.allowMetaPatches = allowMetaPatches;
     this.useCircularStructures = useCircularStructures;
+    this.errors = errors;
+    this.basePath = basePath;
   },
   methods: {
     async ReferenceElement(referenceElement, key, parent, path, ancestors) {
@@ -122,6 +133,8 @@ const OpenApi3_1SwaggerClientDereferenceVisitor = OpenApi3_1DereferenceVisitor.c
         ancestors: ancestorsLineage,
         allowMetaPatches: this.allowMetaPatches,
         useCircularStructures: this.useCircularStructures,
+        errors: this.errors,
+        basePath: this.basePath ?? toPath([...ancestors, parent, referenceElement]),
       });
       fragment = await visitAsync(fragment, visitor, { keyMap, nodeTypeGetter: getNodeType });
 
@@ -180,6 +193,7 @@ const OpenApi3_1SwaggerClientDereferenceVisitor = OpenApi3_1DereferenceVisitor.c
       // transclude the element for a fragment
       return fragment;
     },
+
     async PathItemElement(pathItemElement, key, parent, path, ancestors) {
       const [ancestorsLineage, directAncestors] = this.toAncestorLineage(ancestors);
 
@@ -244,6 +258,8 @@ const OpenApi3_1SwaggerClientDereferenceVisitor = OpenApi3_1DereferenceVisitor.c
         ancestors: ancestorsLineage,
         allowMetaPatches: this.allowMetaPatches,
         useCircularStructures: this.useCircularStructures,
+        errors: this.errors,
+        basePath: this.basePath ?? toPath([...ancestors, parent, pathItemElement]),
       });
       referencedElement = await visitAsync(referencedElement, visitor, {
         keyMap,
@@ -305,6 +321,7 @@ const OpenApi3_1SwaggerClientDereferenceVisitor = OpenApi3_1DereferenceVisitor.c
       // transclude referencing element with merged referenced element
       return mergedPathItemElement;
     },
+
     async SchemaElement(referencingElement, key, parent, path, ancestors) {
       const [ancestorsLineage, directAncestors] = this.toAncestorLineage(ancestors);
 
@@ -416,6 +433,8 @@ const OpenApi3_1SwaggerClientDereferenceVisitor = OpenApi3_1DereferenceVisitor.c
         useCircularStructures: this.useCircularStructures,
         allowMetaPatches: this.allowMetaPatches,
         ancestors: ancestorsLineage,
+        errors: this.errors,
+        basePath: this.basePath ?? toPath([...ancestors, parent, referencingElement]),
       });
       referencedElement = await visitAsync(referencedElement, mergeVisitor, {
         keyMap,
@@ -492,6 +511,7 @@ const OpenApi3_1SwaggerClientDereferenceVisitor = OpenApi3_1DereferenceVisitor.c
       // transclude referencing element with merged referenced element
       return mergedSchemaElement;
     },
+
     async LinkElement() {
       /**
        * OpenApi3_1DereferenceVisitor is doing lookup of Operation Objects
@@ -500,6 +520,29 @@ const OpenApi3_1SwaggerClientDereferenceVisitor = OpenApi3_1DereferenceVisitor.c
        */
       return undefined;
     },
+
+    async ExampleElement(exampleElement, key, parent, path, ancestors) {
+      try {
+        return await OpenApi3_1DereferenceVisitor.compose.methods.ExampleElement.call(
+          this,
+          exampleElement,
+          key,
+          parent,
+          path,
+          ancestors
+        );
+      } catch (error) {
+        const rootCause = getRootCause(error);
+        const wrappedError = wrapError(rootCause, {
+          baseDoc: this.reference.uri,
+          externalValue: exampleElement.externalValue?.toValue(),
+          fullPath: this.basePath ?? toPath([...ancestors, parent, exampleElement]),
+        });
+        this.errors.push(wrappedError);
+
+        return undefined;
+      }
+    },
   },
 });
 

diff --git a/src/resolver/strategies/openapi-3-1.js b/src/resolver/strategies/openapi-3-1.js
@@ -61,6 +61,7 @@ const resolveOpenAPI31Strategy = async (options) => {
     const refSet = ReferenceSet({ refs: [openApiElementReference] });
     if (jsonPointer !== '') refSet.rootRef = null; // reset root reference as we want fragment to become the root reference
 
+    const errors = [];
     const dereferenced = await dereferenceApiDOM(fragmentElement, {
       resolve: {
         /**
@@ -106,13 +107,13 @@ const resolveOpenAPI31Strategy = async (options) => {
           }),
         ],
         refSet,
+        dereferenceOpts: { errors },
       },
     });
-
     const transcluded = transclude(fragmentElement, dereferenced, openApiElement);
     const normalized = skipNormalization ? transcluded : normalizeOpenAPI31(transcluded);
 
-    return { spec: toValue(normalized), errors: [] };
+    return { spec: toValue(normalized), errors };
   } catch (error) {
     if (error instanceof InvalidJsonPointerError || error instanceof EvaluationJsonPointerError) {
       return { spec: null, errors: [] };

diff --git a/...-swagger-client/example-object/__fixtures__/external-value-unresolvable/dereferenced.json b/...-swagger-client/example-object/__fixtures__/external-value-unresolvable/dereferenced.json
@@ -0,0 +1,13 @@
+[
+  {
+    "openapi": "3.1.0",
+    "components": {
+      "examples": {
+        "example1": {
+          "description": "example1 description",
+          "externalValue": "./ex.json"
+        }
+      }
+    }
+  }
+]
diff --git a/...er-client/example-object/__fixtures__/external-value-value-both-defined/dereferenced.json b/...er-client/example-object/__fixtures__/external-value-value-both-defined/dereferenced.json
@@ -0,0 +1,14 @@
+[
+  {
+    "openapi": "3.1.0",
+    "components": {
+      "examples": {
+        "example1": {
+          "description": "example1 description",
+          "value": "sample value",
+          "externalValue": "./ex.json"
+        }
+      }
+    }
+  }
+]
diff --git a/...pidom/reference/dereference/strategies/openapi-3-1-swagger-client/example-object/index.js b/...pidom/reference/dereference/strategies/openapi-3-1-swagger-client/example-object/index.js
@@ -1,7 +1,7 @@
 import path from 'node:path';
 import { toValue } from '@swagger-api/apidom-core';
 import { mediaTypes } from '@swagger-api/apidom-ns-openapi-3-1';
-import { dereference, DereferenceError } from '@swagger-api/apidom-reference/configuration/empty';
+import { dereference } from '@swagger-api/apidom-reference/configuration/empty';
 
 import * as jestSetup from '../__utils__/jest.local.setup.js';
 
@@ -135,14 +135,32 @@ describe('dereference', () => {
           describe('and with unresolvable URI', () => {
             const fixturePath = path.join(rootFixturePath, 'external-value-unresolvable');
 
-            test('should throw error', async () => {
+            test('should dereference', async () => {
+              const rootFilePath = path.join(fixturePath, 'root.json');
+              const actual = await dereference(rootFilePath, {
+                parse: { mediaType: mediaTypes.latest('json') },
+              });
+              const expected = globalThis.loadJsonFile(path.join(fixturePath, 'dereferenced.json'));
+
+              expect(toValue(actual)).toEqual(expected);
+            });
+
+            test('should collect error', async () => {
               const rootFilePath = path.join(fixturePath, 'root.json');
-              const dereferenceThunk = () =>
-                dereference(rootFilePath, {
-                  parse: { mediaType: mediaTypes.latest('json') },
-                });
+              const errors = [];
 
-              await expect(dereferenceThunk()).rejects.toThrow(DereferenceError);
+              await dereference(rootFilePath, {
+                parse: { mediaType: mediaTypes.latest('json') },
+                dereference: { dereferenceOpts: { errors } },
+              });
+
+              expect(errors).toHaveLength(1);
+              expect(errors[0]).toMatchObject({
+                message: expect.stringMatching(/^Could not resolve reference: ENOENT/),
+                baseDoc: expect.stringMatching(/external-value-unresolvable\/root\.json$/),
+                externalValue: './ex.json',
+                fullPath: ['components', 'examples', 'example1'],
+              });
             });
           });
 
@@ -164,14 +182,32 @@ describe('dereference', () => {
           describe('given both value and externalValue fields are defined', () => {
             const fixturePath = path.join(rootFixturePath, 'external-value-value-both-defined');
 
-            test('should throw error', async () => {
+            test('should dereference', async () => {
+              const rootFilePath = path.join(fixturePath, 'root.json');
+              const actual = await dereference(rootFilePath, {
+                parse: { mediaType: mediaTypes.latest('json') },
+              });
+              const expected = globalThis.loadJsonFile(path.join(fixturePath, 'dereferenced.json'));
+
+              expect(toValue(actual)).toEqual(expected);
+            });
+
+            test('should collect error', async () => {
               const rootFilePath = path.join(fixturePath, 'root.json');
-              const dereferenceThunk = () =>
-                dereference(rootFilePath, {
-                  parse: { mediaType: mediaTypes.latest('json') },
-                });
+              const errors = [];
 
-              await expect(dereferenceThunk()).rejects.toThrow(DereferenceError);
+              await dereference(rootFilePath, {
+                parse: { mediaType: mediaTypes.latest('json') },
+                dereference: { dereferenceOpts: { errors } },
+              });
+
+              expect(errors).toHaveLength(1);
+              expect(errors[0]).toMatchObject({
+                message: expect.stringMatching(/^Could not resolve reference: ExampleElement/),
+                baseDoc: expect.stringMatching(/external-value-value-both-defined\/root\.json$/),
+                externalValue: './ex.json',
+                fullPath: ['components', 'examples', 'example1'],
+              });
             });
           });
         });