Skip to content

Improve OpenAPI circular references #3821

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 3 commits into from
Nov 19, 2025
Merged

Improve OpenAPI circular references #3821

Show file tree
Hide file tree
Changes from 2 commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
3c4b418
Improve OpenAPI circular references
nolannbiron Nov 19, 2025
2f487aa
Remove duplicated infos
nolannbiron Nov 19, 2025
9376c39
fix scroll to section
nolannbiron Nov 19, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
6 changes: 6 additions & 0 deletions .changeset/yellow-jobs-nail.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,6 @@
---
'@gitbook/react-openapi': patch
'gitbook': patch
---

Improve OpenAPI circular references
6 changes: 3 additions & 3 deletions packages/gitbook/src/components/DocumentView/OpenAPI/style.css
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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 {
Expand Down Expand Up @@ -249,15 +249,15 @@
}

.openapi-schema-circular {
@apply text-xs text-tint;
@apply text-sm text-tint;
}

.openapi-schema-circular a {
@apply underline;
}

.openapi-schema-circular-glyph {
@apply text-base;
@apply text-base mr-1;
}

/* Schema Enum */
Expand Down
100 changes: 57 additions & 43 deletions packages/react-openapi/src/OpenAPISchema.tsx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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);
Expand Down Expand Up @@ -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>
);
}

Expand Down Expand Up @@ -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>
);
}
Expand Down Expand Up @@ -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;

Expand All @@ -380,38 +388,44 @@ export function OpenAPISchemaPresentation(props: {
required={required}
context={context}
/>
{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>
);
}
Expand Down
Loading