From 5fa0df6e052bcb19c4e5156ac296bc884d5ea024 Mon Sep 17 00:00:00 2001 From: Claude Date: Fri, 20 Nov 2026 21:09:25 +0000 Subject: [PATCH] Resolve GitBook links in OpenAPI schema descriptions to the site's URLs Spec processing now tags app.gitbook.com links in schema, parameter and response descriptions with their content ref (`data-gitbook-ref`). Before rendering an OpenAPI block, point each tagged link at the URL that ref resolves to in the current site, as links in page content already are, instead of the editor URL. The rewrite runs once per spec and request, copies only the changed objects (the spec comes from the data cache), and keeps the original href when a ref doesn't resolve. Co-Authored-By: Claude Opus 5.5 Claude-Session: https://claude.ai/code/session_011HgypRi42LkaRDYNBtfgLF --- packages/gitbook/src/lib/openapi/fetch.ts | 5 +- .../openapi/resolveDescriptionLinks.test.ts | 44 +++++ .../lib/openapi/resolveDescriptionLinks.ts | 165 ++++++++++++++++++ 3 files changed, 213 insertions(+), 1 deletion(-) create mode 100644 packages/gitbook/src/lib/openapi/resolveDescriptionLinks.test.ts create mode 100644 packages/gitbook/src/lib/openapi/resolveDescriptionLinks.ts diff --git a/packages/gitbook/src/lib/openapi/fetch.ts b/packages/gitbook/src/lib/openapi/fetch.ts index 7ec7dc53c..246d03b8b 100644 --- a/packages/gitbook/src/lib/openapi/fetch.ts +++ b/packages/gitbook/src/lib/openapi/fetch.ts @@ -10,6 +10,7 @@ import { } from '@gitbook/openapi-parser'; import { enrichFilesystem } from './enrich'; +import { resolveOpenAPIDescriptionLinks } from './resolveDescriptionLinks'; import type { AnyOpenAPIOperationsBlock, OpenAPISchemasBlock, @@ -41,7 +42,9 @@ export async function fetchOpenAPIFilesystem( // If the reference is a new OpenAPI reference, we return it. if (ref.kind === 'openapi') { assert(resolved.openapi?.filesystem); - return resolved.openapi.filesystem; + return resolveOpenAPIDescriptionLinks(resolved.openapi.filesystem, (contentRef) => + resolveContentRef(contentRef, context) + ); } // For legacy blocks ("swagger"), we need to fetch the file system. return fetchFilesystem(resolved.href, context.space.id); diff --git a/packages/gitbook/src/lib/openapi/resolveDescriptionLinks.test.ts b/packages/gitbook/src/lib/openapi/resolveDescriptionLinks.test.ts new file mode 100644 index 000000000..36f0a22b4 --- /dev/null +++ b/packages/gitbook/src/lib/openapi/resolveDescriptionLinks.test.ts @@ -0,0 +1,44 @@ +import { describe, expect, it } from 'bun:test'; + +import { parseOpenAPI } from '@gitbook/openapi-parser'; + +import { resolveOpenAPIDescriptionLinks } from './resolveDescriptionLinks'; + +const APP_URL = 'https://app.gitbook.com/s/space-1/tables'; + +describe('resolveOpenAPIDescriptionLinks', () => { + it('points tagged links at their resolved URL without mutating the input', async () => { + const original = + `

Fields` + + ` Gone` + + ' Docs

'; + const { filesystem } = await parseOpenAPI({ + value: JSON.stringify({ + openapi: '3.0.0', + info: { title: 'Test', version: '1.0.0' }, + paths: {}, + components: { + schemas: { + Condition: { type: 'object', 'x-gitbook-description-html': original }, + }, + }, + }), + rootURL: null, + }); + + const resolved = await resolveOpenAPIDescriptionLinks(filesystem, async (ref) => + ref.kind === 'page' && ref.page === 'page-1' ? { href: '/docs/tables' } : null + ); + + expect(resolved[0]?.specification.components?.schemas?.Condition).toMatchObject({ + 'x-gitbook-description-html': + '

Fields' + + ` Gone` + + ' Docs

', + }); + // The spec content comes from the data cache, shared across sites. + expect(filesystem[0]?.specification.components?.schemas?.Condition).toMatchObject({ + 'x-gitbook-description-html': original, + }); + }); +}); diff --git a/packages/gitbook/src/lib/openapi/resolveDescriptionLinks.ts b/packages/gitbook/src/lib/openapi/resolveDescriptionLinks.ts new file mode 100644 index 000000000..9083ad8c9 --- /dev/null +++ b/packages/gitbook/src/lib/openapi/resolveDescriptionLinks.ts @@ -0,0 +1,165 @@ +import { type DefaultTreeAdapterMap, parseFragment } from 'parse5'; +import * as React from 'react'; + +import type { ContentRef } from '@gitbook/api'; +import type { Filesystem, OpenAPIV3xDocument } from '@gitbook/openapi-parser'; + +import { escapeHTML } from '@/lib/html'; +import { resolveStringContentRef } from '@/lib/references'; + +const DESCRIPTION_HTML_KEY = 'x-gitbook-description-html'; +// Set by spec processing on links to GitBook content, e.g. `/spaces/{space}/pages/{page}`. +const CONTENT_REF_ATTRIBUTE = 'data-gitbook-ref'; + +type OpenAPIFilesystem = Filesystem; +type HTMLElement = DefaultTreeAdapterMap['element']; +type HTMLNode = DefaultTreeAdapterMap['parentNode'] | DefaultTreeAdapterMap['childNode']; + +// Per request: resolved hrefs depend on the site being rendered. +const getResolvedFilesystems = React.cache( + () => new WeakMap>() +); + +/** + * Point description links that spec processing tagged with a content ref at their URL in the + * current site. Links whose ref doesn't resolve keep the href written in the spec. + * Returns a copy when something changed: the input may be shared through the data cache. + */ +export function resolveOpenAPIDescriptionLinks( + filesystem: OpenAPIFilesystem, + resolveContentRef: (ref: ContentRef) => Promise<{ href: string } | null> +): Promise { + const resolvedFilesystems = getResolvedFilesystems(); + let promise = resolvedFilesystems.get(filesystem); + if (!promise) { + promise = baseResolveOpenAPIDescriptionLinks(filesystem, resolveContentRef); + resolvedFilesystems.set(filesystem, promise); + } + return promise; +} + +async function baseResolveOpenAPIDescriptionLinks( + filesystem: OpenAPIFilesystem, + resolveContentRef: (ref: ContentRef) => Promise<{ href: string } | null> +): Promise { + const taggedHTML = new Set(); + mapDescriptionHTML(filesystem, (html) => { + if (html.includes(CONTENT_REF_ATTRIBUTE)) { + taggedHTML.add(html); + } + return html; + }); + + if (taggedHTML.size === 0) { + return filesystem; + } + + const hrefs = new Map>(); + const resolveHref = (source: string) => { + let href = hrefs.get(source); + if (!href) { + const ref = resolveStringContentRef(source); + href = ref + ? resolveContentRef(ref).then((resolved) => resolved?.href ?? null) + : Promise.resolve(null); + hrefs.set(source, href); + } + return href; + }; + + const rewritten = new Map(); + await Promise.all( + Array.from(taggedHTML, async (html) => { + rewritten.set(html, await rewriteLinks(html, resolveHref)); + }) + ); + + return mapDescriptionHTML(filesystem, (html) => rewritten.get(html) ?? html); +} + +/** + * Replace the href of each tagged link with its resolved URL. + */ +async function rewriteLinks( + html: string, + resolveHref: (source: string) => Promise +): Promise { + const fragment = parseFragment(html, { sourceCodeLocationInfo: true }); + const replacements: { start: number; end: number; value: string }[] = []; + + await Promise.all( + collectLinks(fragment).map(async (link) => { + const source = link.attrs.find((attr) => attr.name === CONTENT_REF_ATTRIBUTE)?.value; + const location = link.sourceCodeLocation?.attrs?.href; + if (!source || !location) { + return; + } + + const href = await resolveHref(source); + if (href) { + replacements.push({ + start: location.startOffset, + end: location.endOffset, + value: `href="${escapeHTML(href)}"`, + }); + } + }) + ); + + // Apply from the end so earlier offsets stay valid. + replacements.sort((a, b) => b.start - a.start); + let result = html; + for (const { start, end, value } of replacements) { + result = result.slice(0, start) + value + result.slice(end); + } + return result; +} + +function collectLinks(node: HTMLNode, links: HTMLElement[] = []): HTMLElement[] { + if ('tagName' in node && node.tagName === 'a') { + links.push(node); + } + if ('childNodes' in node) { + for (const child of node.childNodes) { + collectLinks(child, links); + } + } + return links; +} + +/** + * Map every description HTML in a JSON value, copying only the objects on a changed path. + */ +function mapDescriptionHTML(value: T, transform: (html: string) => string): T { + if (typeof value !== 'object' || value === null) { + return value; + } + + if (Array.isArray(value)) { + let result: unknown[] | null = null; + value.forEach((item, index) => { + const next = mapDescriptionHTML(item, transform); + if (next !== item) { + result ??= [...value]; + result[index] = next; + } + }); + return (result ?? value) as T; + } + + const record = value as Record; + let result: Record | null = null; + // `for...in` over plain JSON objects: several times faster than `Object.entries` on large specs. + for (const key in record) { + const child = record[key]; + const next = + key === DESCRIPTION_HTML_KEY && typeof child === 'string' + ? transform(child) + : mapDescriptionHTML(child, transform); + if (next !== child) { + result ??= { ...record }; + result[key] = next; + } + } + return (result ?? record) as T; +}