Allow excluding certain paths from dereferencing

Author: pimterry

lib/dereference.js

@@ -41,8 +41,10 @@ function crawl (obj, path, pathFromRoot, parents, processedObjects, dereferenced
     circular: false
   };
 
+  let isExcludedPath = options.dereference.excludedPathMatcher;
+
   if (options.dereference.circular === "ignore" || !processedObjects.has(obj)) {
-    if (obj && typeof obj === "object" && !ArrayBuffer.isView(obj)) {
+    if (obj && typeof obj === "object" && !ArrayBuffer.isView(obj) && !isExcludedPath(pathFromRoot)) {
       parents.add(obj);
       processedObjects.add(obj);
 
@@ -55,6 +57,9 @@ function crawl (obj, path, pathFromRoot, parents, processedObjects, dereferenced
         for (const key of Object.keys(obj)) {
           let keyPath = Pointer.join(path, key);
           let keyPathFromRoot = Pointer.join(pathFromRoot, key);
+
+          if (isExcludedPath(keyPathFromRoot)) continue;
+
           let value = obj[key];
           let circular = false;
 

lib/options.js

@@ -73,7 +73,16 @@ $RefParserOptions.defaults = {
      *
      * @type {boolean|string}
      */
-    circular: true
+    circular: true,
+
+    /**
+     * A function, called for each path, which can return true to stop this path and all
+     * subpaths from being dereferenced further. This is useful in schemas where some
+     * subpaths contain literal $ref keys that should not be dereferenced.
+     *
+     * @type {function}
+     */
+    excludedPathMatcher: () => false
   },
 };
 

test/specs/ref-in-excluded-path/dereferenced.js

@@ -0,0 +1,110 @@
+"use strict";
+
+module.exports = {
+  "components": {
+    "examples": {
+      "confirmation-failure": {
+        "value": {
+          "$ref": "#/literal-component-example"
+        }
+      },
+      "confirmation-success": {
+        "value": {
+          "abc": "def"
+        }
+      },
+      "query-example": {
+        "value": "abc"
+      }
+    },
+    "parameters": {
+      "a": {
+        "example": {
+          "$ref": "#/literal-param-component-example"
+        }
+      },
+      "b": {
+        "examples": {
+          "example1": {
+            "value": {
+              "$ref": "#/literal-param-component-examples1"
+            }
+          }
+        }
+      }
+    }
+  },
+  "paths": {
+    "/x/{id}": {
+      "parameters": [
+        {
+          "example": 123,
+          "in": "path",
+          "name": "id"
+        },
+        {
+          "examples": {
+            "e1": {
+              "value": {
+                "$ref": "#/literal-h1"
+              }
+            }
+          },
+          "in": "header",
+          "name": "h1"
+        },
+        {
+          "example": {
+            "$ref": "#/literal-q1"
+          },
+          "in": "query",
+          "name": "q1"
+        },
+        {
+          "examples": {
+            "q2": {
+              "value": "abc"
+            }
+          },
+          "in": "query",
+          "name": "q2"
+        }
+      ],
+      "responses": {
+        "200": {
+          "content": {
+            "application/json": {
+              "examples": {
+                "confirmation-failure": {
+                  "value": {
+                    "$ref": "#/literal-component-example"
+                  }
+                },
+                "confirmation-in-progress": {
+                  "summary": "In progress response",
+                  "value": {
+                    "$ref": "#/abc"
+                  }
+                },
+                "confirmation-success": {
+                  "value": {
+                    "abc": "def"
+                  }
+                }
+              }
+            }
+          }
+        },
+        "400": {
+          "content": {
+            "application/json": {
+              "example": {
+                "$ref": "#/literal-example"
+              }
+            }
+          }
+        }
+      }
+    }
+  }
+};

test/specs/ref-in-excluded-path/ref-in-excluded-path.spec.js

@@ -0,0 +1,21 @@
+"use strict";
+
+const { expect } = require("chai");
+const $RefParser = require("../../..");
+const path = require("../../utils/path");
+const dereferencedSchema = require("./dereferenced");
+
+describe("Schema with literal $refs in examples", () => {
+  it("should exclude the given paths from dereferencing", async () => {
+    let parser = new $RefParser();
+    const schema = await parser.dereference(path.rel("specs/ref-in-excluded-path/ref-in-excluded-path.yaml"), {
+      dereference: {
+        excludedPathMatcher: (path) => {
+          return /\/example(\/|$|s\/[^\/]+\/value(\/|$))/.test(path);
+        }
+      }
+    });
+    expect(schema).to.equal(parser.schema);
+    expect(schema).to.deep.equal(dereferencedSchema);
+  });
+});

test/specs/ref-in-excluded-path/ref-in-excluded-path.yaml

@@ -0,0 +1,60 @@
+# Minimal parts of an OpenAPI 3.1.0 document, including various examples that should be literal:
+paths:
+  '/x/{id}':
+    parameters:
+      - name: id
+        in: path
+        example:
+          123
+      - name: h1
+        in: header
+        examples:
+          e1:
+            value: # Literal value
+              $ref: '#/literal-h1'
+      - name: q1
+        in: query
+        example:
+          $ref: '#/literal-q1'
+      - name: q2
+        in: query
+        examples:
+          q2:
+            $ref: '#/components/examples/query-example'
+    responses:
+      '200':
+        content:
+          application/json:
+            examples:
+              confirmation-success: # Real ref
+                $ref: '#/components/examples/confirmation-success'
+              confirmation-in-progress:
+                summary: In progress response
+                value: # Literal ref! The $ref should not be dereferenced
+                  $ref: '#/abc'
+              confirmation-failure: # Real ref to example with literal $ref
+                $ref: '#/components/examples/confirmation-failure'
+      '400':
+        content:
+          application/json:
+            example:
+              $ref: '#/literal-example'
+components:
+  examples:
+    query-example:
+      value: abc
+    confirmation-success:
+      value:
+        abc: def
+    confirmation-failure:
+      value: # Literal value! The $ref should not be dereferenced
+        $ref: '#/literal-component-example'
+  parameters:
+    a:
+      example:
+        $ref: '#/literal-param-component-example'
+    b:
+      examples:
+        example1:
+          value:
+            $ref: '#/literal-param-component-examples1'