From 3c4b4184a5d69d6a4d7ba15777c0f239989b88cf Mon Sep 17 00:00:00 2001
From: Nolann Biron <biron.nolann@gmail.com>
Date: Wed, 19 Nov 2025 14:59:50 +0100
Subject: [PATCH 1/3] Improve OpenAPI circular references

---
 .changeset/yellow-jobs-nail.md                |  6 ++++
 .../components/DocumentView/OpenAPI/style.css |  6 ++--
 packages/react-openapi/src/OpenAPISchema.tsx  | 31 ++++++++++++-------
 3 files changed, 29 insertions(+), 14 deletions(-)
 create mode 100644 .changeset/yellow-jobs-nail.md

diff --git a/.changeset/yellow-jobs-nail.md b/.changeset/yellow-jobs-nail.md
new file mode 100644
index 0000000000..c066da6b08
--- /dev/null
+++ b/.changeset/yellow-jobs-nail.md
@@ -0,0 +1,6 @@
+---
+'@gitbook/react-openapi': patch
+'gitbook': patch
+---
+
+Improve OpenAPI circular references
diff --git a/packages/gitbook/src/components/DocumentView/OpenAPI/style.css b/packages/gitbook/src/components/DocumentView/OpenAPI/style.css
index 53602c41df..5bccd59cfd 100644
--- a/packages/gitbook/src/components/DocumentView/OpenAPI/style.css
+++ b/packages/gitbook/src/components/DocumentView/OpenAPI/style.css
@@ -173,7 +173,7 @@
 
 .openapi-schema,
 .openapi-disclosure {
-    @apply py-2.5 flex flex-col gap-2;
+    @apply py-2.5 flex flex-col gap-2 scroll-mt-(--toc-top-offset);
 }
 
 .openapi-schema-properties .openapi-schema: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 */
diff --git a/packages/react-openapi/src/OpenAPISchema.tsx b/packages/react-openapi/src/OpenAPISchema.tsx
index 63821b0193..b2189d97eb 100644
--- a/packages/react-openapi/src/OpenAPISchema.tsx
+++ b/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);
@@ -99,15 +105,15 @@ function OpenAPISchemaProperty(
 
     if (properties?.length) {
         return (
-            <OpenAPIDisclosure
-                icon={context.icons.plus}
-                className={clsx('openapi-schema', className)}
-                header={header}
-                label={(isExpanded) => getDisclosureLabel({ schema, isExpanded, context })}
-                {...rest}
-            >
-                {content}
-            </OpenAPIDisclosure>
+            <div id={id} className={clsx('openapi-schema', className)} {...rest}>
+                <OpenAPIDisclosure
+                    icon={context.icons.plus}
+                    header={header}
+                    label={(isExpanded) => getDisclosureLabel({ schema, isExpanded, context })}
+                >
+                    {content}
+                </OpenAPIDisclosure>
+            </div>
         );
     }
 
@@ -289,8 +295,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>
     );
 }
@@ -361,9 +367,11 @@ function OpenAPISchemaEnum(props: {
 export function OpenAPISchemaPresentation(props: {
     property: OpenAPISchemaPropertyEntry;
     context: OpenAPIClientContext;
+    circularRefId?: string;
 }) {
     const {
         property: { schema, propertyName, required, isDiscriminatorProperty },
+        circularRefId,
         context,
     } = props;
 
@@ -380,6 +388,7 @@ export function OpenAPISchemaPresentation(props: {
                 required={required}
                 context={context}
             />
+            {circularRefId ? <OpenAPISchemaCircularRef id={circularRefId} schema={schema} /> : null}
             {typeof schema['x-deprecated-sunset'] === 'string' ? (
                 <div className="openapi-deprecated-sunset openapi-schema-description openapi-markdown">
                     Sunset date:{' '}

From 2f487aacdef98db5cf1dd665c365bcb552382554 Mon Sep 17 00:00:00 2001
From: Nolann Biron <biron.nolann@gmail.com>
Date: Wed, 19 Nov 2025 15:03:21 +0100
Subject: [PATCH 2/3] Remove duplicated infos

---
 packages/react-openapi/src/OpenAPISchema.tsx | 71 +++++++++++---------
 1 file changed, 38 insertions(+), 33 deletions(-)

diff --git a/packages/react-openapi/src/OpenAPISchema.tsx b/packages/react-openapi/src/OpenAPISchema.tsx
index b2189d97eb..ed7cca53aa 100644
--- a/packages/react-openapi/src/OpenAPISchema.tsx
+++ b/packages/react-openapi/src/OpenAPISchema.tsx
@@ -388,39 +388,44 @@ export function OpenAPISchemaPresentation(props: {
                 required={required}
                 context={context}
             />
-            {circularRefId ? <OpenAPISchemaCircularRef id={circularRefId} schema={schema} /> : null}
-            {typeof schema['x-deprecated-sunset'] === 'string' ? (
-                <div className="openapi-deprecated-sunset openapi-schema-description openapi-markdown">
-                    Sunset date:{' '}
-                    <span className="openapi-deprecated-sunset-date">
-                        {schema['x-deprecated-sunset']}
-                    </span>
-                </div>
-            ) : null}
-            {description ? (
-                <Markdown source={description} className="openapi-schema-description" />
-            ) : null}
-            {schema.default !== undefined ? (
-                <span className="openapi-schema-default">
-                    Default:{' '}
-                    <code>
-                        {typeof schema.default === 'string' && schema.default
-                            ? schema.default
-                            : stringifyOpenAPI(schema.default)}
-                    </code>
-                </span>
-            ) : null}
-            {typeof example === 'string' ? (
-                <span className="openapi-schema-example">
-                    Example: <code>{example}</code>
-                </span>
-            ) : null}
-            {schema.pattern ? (
-                <span className="openapi-schema-pattern">
-                    Pattern: <code>{schema.pattern}</code>
-                </span>
-            ) : null}
-            <OpenAPISchemaEnum schema={schema} 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:{' '}
+                            <span className="openapi-deprecated-sunset-date">
+                                {schema['x-deprecated-sunset']}
+                            </span>
+                        </div>
+                    ) : null}
+                    {description ? (
+                        <Markdown source={description} className="openapi-schema-description" />
+                    ) : null}
+                    {schema.default !== undefined ? (
+                        <span className="openapi-schema-default">
+                            Default:{' '}
+                            <code>
+                                {typeof schema.default === 'string' && schema.default
+                                    ? schema.default
+                                    : stringifyOpenAPI(schema.default)}
+                            </code>
+                        </span>
+                    ) : null}
+                    {typeof example === 'string' ? (
+                        <span className="openapi-schema-example">
+                            Example: <code>{example}</code>
+                        </span>
+                    ) : null}
+                    {schema.pattern ? (
+                        <span className="openapi-schema-pattern">
+                            Pattern: <code>{schema.pattern}</code>
+                        </span>
+                    ) : null}
+                    <OpenAPISchemaEnum schema={schema} context={context} />
+                </>
+            )}
         </div>
     );
 }

From 9376c39585b83a72e325a5b709a95f77b4a323ad Mon Sep 17 00:00:00 2001
From: Nolann Biron <biron.nolann@gmail.com>
Date: Wed, 19 Nov 2025 22:00:38 +0100
Subject: [PATCH 3/3] fix scroll to section

---
 .../components/DocumentView/OpenAPI/style.css |  4 ++--
 packages/react-openapi/src/OpenAPISchema.tsx  | 22 +++++++++----------
 2 files changed, 13 insertions(+), 13 deletions(-)

diff --git a/packages/gitbook/src/components/DocumentView/OpenAPI/style.css b/packages/gitbook/src/components/DocumentView/OpenAPI/style.css
index 5bccd59cfd..ca2eb3e9d6 100644
--- a/packages/gitbook/src/components/DocumentView/OpenAPI/style.css
+++ b/packages/gitbook/src/components/DocumentView/OpenAPI/style.css
@@ -173,7 +173,7 @@
 
 .openapi-schema,
 .openapi-disclosure {
-    @apply py-2.5 flex flex-col gap-2 scroll-mt-(--toc-top-offset);
+    @apply py-2.5 flex flex-col gap-2;
 }
 
 .openapi-schema-properties .openapi-schema:last-child {
@@ -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 {
diff --git a/packages/react-openapi/src/OpenAPISchema.tsx b/packages/react-openapi/src/OpenAPISchema.tsx
index ed7cca53aa..7f9d0217ac 100644
--- a/packages/react-openapi/src/OpenAPISchema.tsx
+++ b/packages/react-openapi/src/OpenAPISchema.tsx
@@ -64,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;
@@ -105,15 +105,13 @@ function OpenAPISchemaProperty(
 
     if (properties?.length) {
         return (
-            <div id={id} className={clsx('openapi-schema', className)} {...rest}>
-                <OpenAPIDisclosure
-                    icon={context.icons.plus}
-                    header={header}
-                    label={(isExpanded) => getDisclosureLabel({ schema, isExpanded, context })}
-                >
-                    {content}
-                </OpenAPIDisclosure>
-            </div>
+            <OpenAPIDisclosure
+                icon={context.icons.plus}
+                header={header}
+                label={(isExpanded) => getDisclosureLabel({ schema, isExpanded, context })}
+            >
+                {content}
+            </OpenAPIDisclosure>
         );
     }
 
@@ -365,11 +363,13 @@ 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,
@@ -379,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)}