fix: circular references crashing the sdk

packages/api/__tests__/__fixtures__/circular.oas.json

@@ -0,0 +1,62 @@
+{
+  "openapi": "3.0.1",
+  "info": {
+    "title": "API definition with a circular $ref",
+    "version": "1.0.0"
+  },
+  "servers": [
+    {
+      "url": "https://httpbin.org"
+    }
+  ],
+  "paths": {
+    "/anything": {
+      "get": {
+        "responses": {
+          "200": {
+            "description": "OK"
+          },
+          "404": {
+            "description": "Not found",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/ErrorMessage"
+                }
+              }
+            }
+          }
+        }
+      }
+    }
+  },
+  "components": {
+    "schemas": {
+      "ErrorMessage": {
+        "type": "object",
+        "additionalProperties": false,
+        "properties": {
+          "statusCode": {
+            "type": "integer",
+            "format": "int32"
+          },
+          "error": {
+            "type": "string",
+            "nullable": true
+          },
+          "inner": {
+            "$ref": "#/components/schemas/ErrorMessage"
+          },
+          "canBeRetried": {
+            "type": "string",
+            "enum": ["Unknown", "Yes", "No"]
+          },
+          "detailedErrorCode": {
+            "type": "integer",
+            "format": "int32"
+          }
+        }
+      }
+    }
+  }
+}

packages/api/__tests__/cache.test.js

@@ -37,6 +37,10 @@ beforeEach(async () => {
   readmeExampleYaml = await realFs.readFile(require.resolve('@readme/oas-examples/3.0/yaml/readme.yaml'), 'utf8');
 
   vol.fromJSON({
+    [`${[examplesDir]}/circular.json`]: await realFs.readFile(
+      require.resolve('./__fixtures__/circular.oas.json'),
+      'utf8'
+    ),
     [`${[examplesDir]}/invalid-openapi.json`]: JSON.stringify(pkg),
     [`${[examplesDir]}/readme.json`]: readmeExampleJson,
     [`${[examplesDir]}/readme.yaml`]: readmeExampleYaml,
@@ -201,6 +205,17 @@ describe('#save()', () => {
 
     expect(cacheStore.isCached()).toBe(true);
   });
+
+  it('should be able to cache a definition that contains a circular reference', async () => {
+    const file = path.join(examplesDir, 'circular.json');
+    const cacheStore = new Cache(file);
+
+    expect(cacheStore.isCached()).toBe(false);
+
+    await cacheStore.saveFile();
+
+    expect(cacheStore.isCached()).toBe(true);
+  });
 });
 
 describe('#get', () => {

packages/api/__tests__/lib/prepareParams.test.js

@@ -1,6 +1,5 @@
 const fs = require('fs');
 const Oas = require('oas');
-const $RefParser = require('@apidevtools/json-schema-ref-parser');
 const readmeExample = require('@readme/oas-examples/3.0/json/readme.json');
 const usptoExample = require('@readme/oas-examples/3.0/json/uspto.json');
 const payloadExamples = require('../__fixtures__/payloads.oas.json');
@@ -12,11 +11,11 @@ describe('#prepareParams', () => {
   let usptoSpec;
 
   beforeAll(async () => {
-    let schema = await $RefParser.dereference(readmeExample);
-    readmeSpec = new Oas(schema);
+    readmeSpec = new Oas(readmeExample);
+    await readmeSpec.dereference();
 
-    schema = await $RefParser.dereference(usptoExample);
-    usptoSpec = new Oas(schema);
+    usptoSpec = new Oas(usptoExample);
+    await usptoSpec.dereference();
   });
 
   it('should prepare nothing if nothing was supplied', async () => {

packages/api/package.json

@@ -23,7 +23,6 @@
     "node": "^12 || ^14 || ^16"
   },
   "dependencies": {
-    "@apidevtools/json-schema-ref-parser": "^9.0.1",
     "@apidevtools/swagger-parser": "^10.0.1",
     "@readme/oas-to-har": "^13.7.2",
     "datauri": "^4.1.0",
@@ -35,7 +34,7 @@
     "make-dir": "^3.1.0",
     "mimer": "^2.0.2",
     "node-fetch": "^2.6.0",
-    "oas": "^14.5.1"
+    "oas": "^14.7.0"
   },
   "devDependencies": {
     "@readme/eslint-config": "^7.2.2",

packages/api/src/cache.js

@@ -1,6 +1,5 @@
 const fetch = require('node-fetch');
 const SwaggerParser = require('@apidevtools/swagger-parser');
-const $RefParser = require('@apidevtools/json-schema-ref-parser');
 const yaml = require('js-yaml');
 const crypto = require('crypto');
 const findCacheDir = require('find-cache-dir');
@@ -127,17 +126,22 @@ class SdkCache {
       return resolve(json);
     })
       .then(res => {
-        return SwaggerParser.validate(res).catch(err => {
+        // The `validate` method handles dereferencing for us.
+        return SwaggerParser.validate(res, {
+          dereference: {
+            // If circular `$refs` are ignored they'll remain in the API definition as `$ref: String`. This allows us to
+            // not only do easy circular reference detection but also stringify and  save dereferenced API definitions
+            // back into the cache directory.
+            circular: 'ignore',
+          },
+        }).catch(err => {
           if (/is not a valid openapi api definition/i.test(err.message)) {
             throw new Error("Sorry, that doesn't look like a valid OpenAPI definition.");
           }
 
           throw err;
         });
       })
-      .then(res => {
-        return $RefParser.dereference(res);
-      })
       .then(async spec => {
         if (!fs.existsSync(self.dir)) {
           fs.mkdirSync(self.dir, { recursive: true });