Add self-referencing schema detection

Author: sserrata

packages/docusaurus-plugin-openapi-docs/src/openapi/__fixtures__/examples/self-ref.yaml

@@ -0,0 +1,15 @@
+openapi: 3.0.3
+info:
+  title: Self Ref Example
+  version: 1.0.0
+paths: {}
+components:
+  schemas:
+    Node:
+      title: Node
+      type: object
+      properties:
+        name:
+          type: string
+        child:
+          $ref: "#/components/schemas/Node"

packages/docusaurus-plugin-openapi-docs/src/openapi/circular.test.ts

@@ -0,0 +1,25 @@
+/* ============================================================================
+ * Copyright (c) Palo Alto Networks
+ *
+ * This source code is licensed under the MIT license found in the
+ * LICENSE file in the root directory of this source tree.
+ * ========================================================================== */
+
+import path from "path";
+
+// eslint-disable-next-line import/no-extraneous-dependencies
+import { posixPath } from "@docusaurus/utils";
+
+import { loadAndResolveSpec } from "./utils/loadAndResolveSpec";
+
+describe("circular references", () => {
+  it("flags self referencing schemas", async () => {
+    const file = posixPath(
+      path.join(__dirname, "__fixtures__/examples/self-ref.yaml")
+    );
+    const spec: any = await loadAndResolveSpec(file);
+    expect(spec.components.schemas.Node.properties.child).toBe(
+      "circular(Node)"
+    );
+  });
+});

packages/docusaurus-plugin-openapi-docs/src/openapi/utils/loadAndResolveSpec.ts

@@ -123,20 +123,13 @@ async function resolveJsonRefs(specUrlOrObject: object | string) {
   }
 }
 
-function markCircularRefs(obj: any, stack: any[] = []): boolean {
+function markCircularRefs(obj: any, stack: any[] = []): boolean | "circular" {
   if (!obj || typeof obj !== "object") {
     return false;
   }
 
-  const pos = stack.indexOf(obj);
-  if (pos !== -1) {
-    for (let i = pos + 1; i < stack.length; i++) {
-      const cyc = stack[i];
-      if (cyc && typeof cyc === "object") {
-        cyc["x-circular-ref"] = true;
-      }
-    }
-    return true;
+  if (stack.includes(obj)) {
+    return "circular";
   }
 
   stack.push(obj);
@@ -146,7 +139,11 @@ function markCircularRefs(obj: any, stack: any[] = []): boolean {
     for (let i = 0; i < obj.length; i++) {
       const val = obj[i];
       if (typeof val === "object" && val !== null) {
-        if (markCircularRefs(val, stack)) {
+        const res = markCircularRefs(val, stack);
+        if (res) {
+          if (res === "circular") {
+            obj[i] = { ...val, "x-circular-ref": true };
+          }
           foundCircular = true;
         }
       }
@@ -155,7 +152,11 @@ function markCircularRefs(obj: any, stack: any[] = []): boolean {
     for (const key of Object.keys(obj)) {
       const val = obj[key];
       if (typeof val === "object" && val !== null) {
-        if (markCircularRefs(val, stack)) {
+        const res = markCircularRefs(val, stack);
+        if (res) {
+          if (res === "circular") {
+            obj[key] = { ...val, "x-circular-ref": true };
+          }
           foundCircular = true;
         }
       }