fix(oas3): support dereferencing recursive references

Author: kylef

packages/openapi3-parser/lib/parser/oas/parseReferenceObject.js

@@ -12,6 +12,33 @@ const parseString = require('../parseString');
 const name = 'Reference Object';
 const requiredKeys = ['$ref'];
 
+/**
+ * Recursively dereference an element in the given component
+ *
+ * @param namespace {Namespace}
+ * @param component {ObjectElement}
+ * @param ref {StringElement}
+ * @param element {Element}
+ * @param parents {string[]} an optional collections of traversed parents
+ *
+ * @returns Element
+ */
+function dereference(namespace, component, ref, element, parents = []) {
+  if (parents && parents.includes(element.element)) {
+    // We've already cycled through this element. We're in a circular loop
+    parents.shift();
+    return createError(namespace, `Reference cannot be circular, '${ref.toValue()}' causes a circular reference via ${parents.join(', ')}`, ref);
+  }
+
+  const match = component.get(element.element);
+  if (match) {
+    parents.push(element.element);
+    return dereference(namespace, component, ref, match, parents);
+  }
+
+  return element;
+}
+
 /**
  * Parse Reference Object
  *
@@ -76,7 +103,7 @@ function parseReferenceObject(context, componentName, element, returnReferenceEl
     return new namespace.elements.ParseResult(
       component
         .filter((value, key) => key.toValue() === componentId && value)
-        .map(value => value)
+        .map(value => dereference(namespace, component, ref, value))
     );
   };
 

packages/openapi3-parser/test/unit/parser/oas/parseReferenceObject-test.js

@@ -88,6 +88,29 @@ describe('Reference Object', () => {
     expect(parseResult.length).to.equal(0);
   });
 
+  it('can parse a reference to a reference', () => {
+    const nodeAlias = new namespace.elements.Element();
+    nodeAlias.element = 'Node';
+
+    context.state.components = new namespace.elements.Object({
+      schemas: {
+        Node: 'example',
+        NodeAlias: nodeAlias,
+      },
+    });
+
+    const reference = new namespace.elements.Object({
+      $ref: '#/components/schemas/NodeAlias',
+    });
+    const parseResult = parse(context, 'schemas', reference);
+
+    expect(parseResult.length).to.equal(1);
+    const structure = parseResult.get(0);
+    expect(structure).to.be.instanceof(namespace.elements.String);
+    expect(structure.element).to.equal('string');
+    expect(structure.toValue()).to.equal('example');
+  });
+
   describe('invalid references', () => {
     it('errors when parsing a non-components reference', () => {
       const reference = new namespace.elements.Object({
@@ -145,6 +168,32 @@ describe('Reference Object', () => {
 
       expect(parseResult).to.contain.error("'#/components' is not defined");
     });
+
+    it('errors when parsing reference causing circular reference', () => {
+      const createElement = (name) => {
+        const element = new namespace.elements.Element();
+        element.element = name;
+        return element;
+      };
+
+      context.state.components = new namespace.elements.Object({
+        schemas: {
+          A: createElement('B'),
+          B: createElement('C'),
+          C: createElement('D'),
+          D: createElement('A'),
+        },
+      });
+
+      const reference = new namespace.elements.Object({
+        $ref: '#/components/schemas/A',
+      });
+
+      const parseResult = parse(context, 'schemas', reference);
+      expect(parseResult).to.contain.error(
+        "Reference cannot be circular, '#/components/schemas/A' causes a circular reference via C, D, A"
+      );
+    });
   });
 
   describe('warnings for invalid properties', () => {