feat: support circular labels from x-circular-ref

Author: sserrata

packages/docusaurus-plugin-openapi-docs/src/markdown/createSchema.ts

@@ -784,24 +784,42 @@ export function createNodes(
 
   if (schema.allOf !== undefined) {
     const circularItems = schema.allOf.filter((item: any) => {
-      return typeof item === "string" && item.includes("circular");
+      if (typeof item === "string" && item.includes("circular")) {
+        return true;
+      }
+      if (typeof item === "object" && item["x-circular-ref"]) {
+        return true;
+      }
+      return false;
     });
 
     for (const label of circularItems) {
+      const schemaName =
+        typeof label === "string"
+          ? label
+          : label.title
+            ? `circular(${label.title})`
+            : "circular()";
       nodes.push(
         create("SchemaItem", {
           collapsible: false,
           name: "",
           required: false,
-          schemaName: label,
+          schemaName,
           qualifierMessage: undefined,
           schema: {},
         })
       );
     }
 
     const rest = schema.allOf.filter((item: any) => {
-      return !(typeof item === "string" && item.includes("circular"));
+      if (typeof item === "string" && item.includes("circular")) {
+        return false;
+      }
+      if (typeof item === "object" && item["x-circular-ref"]) {
+        return false;
+      }
+      return true;
     });
 
     if (rest.length) {
@@ -828,14 +846,25 @@ export function createNodes(
   if (schema.type !== undefined) {
     if (schema.allOf) {
       //handle circular result in allOf
-      if (schema.allOf.length && typeof schema.allOf[0] === "string") {
+      const first: any = schema.allOf[0];
+      if (
+        schema.allOf.length &&
+        ((typeof first === "string" && first.includes("circular")) ||
+          (typeof first === "object" && first["x-circular-ref"]))
+      ) {
+        const label =
+          typeof first === "string"
+            ? first
+            : first.title
+              ? `circular(${first.title})`
+              : "circular()";
         return create("div", {
           style: {
             marginTop: ".5rem",
             marginBottom: ".5rem",
             marginLeft: "1rem",
           },
-          children: createDescription(schema.allOf[0]),
+          children: createDescription(label),
         });
       }
     }

packages/docusaurus-plugin-openapi-docs/src/markdown/schema.ts

@@ -11,6 +11,9 @@ function prettyName(schema: SchemaObject | string, circular?: boolean) {
   if (typeof schema === "string") {
     return schema.startsWith("circular(") ? schema : "";
   }
+  if (schema["x-circular-ref"]) {
+    return schema.title ? `circular(${schema.title})` : "circular()";
+  }
   if (schema.format) {
     if (schema.type) {
       return `${schema.type}<${schema.format}>`;

packages/docusaurus-theme-openapi-docs/src/theme/SchemaItem/index.tsx

@@ -97,10 +97,16 @@ export default function SchemaItem(props: Props) {
       ? schemaName.match(/^circular\\(([^)]*)\\)/)
       : null;
 
-  const renderCircular = guard(circularMatch, () => (
-    <span className="openapi-schema__circular">
-      {circularMatch ? `circular(${circularMatch[1]})` : "circular"}
-    </span>
+  const circularTitle = schema?.["x-circular-ref"]
+    ? schema.title
+      ? `circular(${schema.title})`
+      : "circular"
+    : circularMatch
+      ? `circular(${circularMatch[1]})`
+      : null;
+
+  const renderCircular = guard(circularTitle, () => (
+    <span className="openapi-schema__circular">{circularTitle}</span>
   ));
 
   const renderEnumDescriptions = guard(