Improve OpenAPI circular references (#3821)

.changeset/yellow-jobs-nail.md

@@ -0,0 +1,6 @@
+---
+'@gitbook/react-openapi': patch
+'gitbook': patch
+---
+
+Improve OpenAPI circular references

packages/gitbook/src/components/DocumentView/OpenAPI/style.css

@@ -182,7 +182,7 @@
 
 /* Schema Presentation */
 .openapi-schema-presentation {
-    @apply flex flex-col gap-1 font-normal;
+    @apply flex flex-col gap-1 font-normal scroll-mt-[calc(var(--toc-top-offset)+0.5rem)];
 }
 
 .openapi-schema-properties:last-child {
@@ -249,7 +249,7 @@
 }
 
 .openapi-schema-circular {
-    @apply text-xs text-tint;
+    @apply text-sm text-tint;
 }
 
 .openapi-schema-circular a {
@@ -257,7 +257,7 @@
 }
 
 .openapi-schema-circular-glyph {
-    @apply text-base;
+    @apply text-base mr-1;
 }
 
 /* Schema Enum */

packages/react-openapi/src/OpenAPISchema.tsx

@@ -47,7 +47,13 @@ function OpenAPISchemaProperty(
     const circularRefId = parentCircularRefs.get(schema);
     // Avoid recursing infinitely, and instead render a link to the parent schema
     if (circularRefId) {
-        return <OpenAPISchemaCircularRef id={circularRefId} schema={schema} />;
+        return (
+            <OpenAPISchemaPresentation
+                context={context}
+                property={property}
+                circularRefId={circularRefId}
+            />
+        );
     }
 
     const circularRefs = new Map(parentCircularRefs);
@@ -58,7 +64,7 @@ function OpenAPISchemaProperty(
     const ancestors = new Set(circularRefs.keys());
     const alternatives = getSchemaAlternatives(schema, ancestors);
 
-    const header = <OpenAPISchemaPresentation context={context} property={property} />;
+    const header = <OpenAPISchemaPresentation id={id} context={context} property={property} />;
     const content = (() => {
         if (alternatives?.schemas) {
             const { schemas, discriminator } = alternatives;
@@ -101,10 +107,8 @@ function OpenAPISchemaProperty(
         return (
             <OpenAPIDisclosure
                 icon={context.icons.plus}
-                className={clsx('openapi-schema', className)}
                 header={header}
                 label={(isExpanded) => getDisclosureLabel({ schema, isExpanded, context })}
-                {...rest}
             >
                 {content}
             </OpenAPIDisclosure>
@@ -289,8 +293,8 @@ function OpenAPISchemaCircularRef(props: { id: string; schema: OpenAPIV3.SchemaO
 
     return (
         <div className="openapi-schema-circular">
+            <span className="openapi-schema-circular-glyph">⤷</span>
             Circular reference to <a href={`#${id}`}>{getSchemaTitle(schema)}</a>{' '}
-            <span className="openapi-schema-circular-glyph">↩</span>
         </div>
     );
 }
@@ -359,11 +363,15 @@ function OpenAPISchemaEnum(props: {
  * Render the top row of a schema. e.g: name, type, and required status.
  */
 export function OpenAPISchemaPresentation(props: {
+    id?: string;
     property: OpenAPISchemaPropertyEntry;
     context: OpenAPIClientContext;
+    circularRefId?: string;
 }) {
     const {
+        id,
         property: { schema, propertyName, required, isDiscriminatorProperty },
+        circularRefId,
         context,
     } = props;
 
@@ -371,7 +379,7 @@ export function OpenAPISchemaPresentation(props: {
     const example = resolveFirstExample(schema);
 
     return (
-        <div className="openapi-schema-presentation">
+        <div id={id} className="openapi-schema-presentation">
             <OpenAPISchemaName
                 schema={schema}
                 type={getSchemaTitle(schema)}
@@ -380,6 +388,10 @@ export function OpenAPISchemaPresentation(props: {
                 required={required}
                 context={context}
             />
+            {circularRefId ? (
+                <OpenAPISchemaCircularRef id={circularRefId} schema={schema} />
+            ) : (
+                <>
                     {typeof schema['x-deprecated-sunset'] === 'string' ? (
                         <div className="openapi-deprecated-sunset openapi-schema-description openapi-markdown">
                             Sunset date:{' '}
@@ -412,6 +424,8 @@ export function OpenAPISchemaPresentation(props: {
                         </span>
                     ) : null}
                     <OpenAPISchemaEnum schema={schema} context={context} />
+                </>
+            )}
         </div>
     );
 }