mirror of
https://github.com/GitbookIO/gitbook.git
synced 2026-11-21 15:52:36 +00:00
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 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_011HgypRi42LkaRDYNBtfgLF
This commit is contained in:
@@ -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);
|
||||
|
||||
@@ -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 =
|
||||
`<p><a href="${APP_URL}" data-gitbook-ref="/spaces/space-1/pages/page-1">Fields</a>` +
|
||||
` <a href="${APP_URL}" data-gitbook-ref="/spaces/space-1/pages/missing">Gone</a>` +
|
||||
' <a href="https://example.com">Docs</a></p>';
|
||||
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':
|
||||
'<p><a href="/docs/tables" data-gitbook-ref="/spaces/space-1/pages/page-1">Fields</a>' +
|
||||
` <a href="${APP_URL}" data-gitbook-ref="/spaces/space-1/pages/missing">Gone</a>` +
|
||||
' <a href="https://example.com">Docs</a></p>',
|
||||
});
|
||||
// The spec content comes from the data cache, shared across sites.
|
||||
expect(filesystem[0]?.specification.components?.schemas?.Condition).toMatchObject({
|
||||
'x-gitbook-description-html': original,
|
||||
});
|
||||
});
|
||||
});
|
||||
@@ -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<OpenAPIV3xDocument>;
|
||||
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<OpenAPIFilesystem, Promise<OpenAPIFilesystem>>()
|
||||
);
|
||||
|
||||
/**
|
||||
* 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<OpenAPIFilesystem> {
|
||||
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<OpenAPIFilesystem> {
|
||||
const taggedHTML = new Set<string>();
|
||||
mapDescriptionHTML(filesystem, (html) => {
|
||||
if (html.includes(CONTENT_REF_ATTRIBUTE)) {
|
||||
taggedHTML.add(html);
|
||||
}
|
||||
return html;
|
||||
});
|
||||
|
||||
if (taggedHTML.size === 0) {
|
||||
return filesystem;
|
||||
}
|
||||
|
||||
const hrefs = new Map<string, Promise<string | null>>();
|
||||
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<string, string>();
|
||||
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<string | null>
|
||||
): Promise<string> {
|
||||
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<T>(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<string, unknown>;
|
||||
let result: Record<string, unknown> | 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;
|
||||
}
|
||||
Reference in New Issue
Block a user