vocs 2.0.17 → 2.1.2

package/dist/internal/openapi/parser.d.ts

@@ -0,0 +1,181 @@
+import type * as OpenApi from './openapi.js';
+/**
+ * HTTP methods recognized on an OpenAPI path item, in canonical display order.
+ */
+export declare const methods: readonly ["get", "post", "put", "patch", "delete", "head", "options", "trace"];
+export type Method = (typeof methods)[number];
+/**
+ * Intermediate representation of a parsed OpenAPI document.
+ *
+ * This is the serializable shape consumed by the React rendering layer (via the
+ * `virtual:vocs/openapi` module) and the sidebar generator. It intentionally
+ * keeps raw JSON Schema objects (`parameters`, `requestBody`, `responses`) so
+ * the renderer can display them without a lossy transform.
+ */
+export type Ir = {
+    /** Mount path the section is served at (e.g. `/api`). */
+    path: string;
+    /**
+     * Spec source handed to the interactive client (Scalar API client). A `url`
+     * when the configured spec is a URL (the client fetches it directly), else
+     * the upgraded document `content` so the client works for file/inline specs.
+     */
+    client: {
+        url: string;
+    } | {
+        content: Record<string, unknown>;
+    };
+    /** Document metadata. */
+    info: {
+        title: string;
+        version?: string | undefined;
+        description?: string | undefined;
+    };
+    /** Servers the API is hosted at. */
+    servers: IrServer[];
+    /** Operations grouped by category (tag or path segment). */
+    groups: IrGroup[];
+    /**
+     * Doc-only "trait" pages: tags marked `x-traitTag: true` (Redoc convention),
+     * which carry Markdown `description` content but no operations. The standalone
+     * handler renders each as a guide page nested under `Introduction`.
+     */
+    traits: IrTrait[];
+    /** Named security schemes from `components.securitySchemes`. */
+    securitySchemes: Record<string, IrSecurityScheme>;
+};
+export type IrTrait = {
+    /** Stable slug used as the page route segment. */
+    id: string;
+    /** Display name (the page title fallback). */
+    name: string;
+    /** Page body (Markdown). */
+    description?: string | undefined;
+    /** Optional subtitle rendered under the title (`x-subtitle`). */
+    subtitle?: string | undefined;
+    /**
+     * Sidebar group to nest the page under (`x-parent`, a tag/group name). When
+     * omitted, the page nests under `Introduction`. When it names an existing
+     * operation group, the page joins that group; otherwise a new sidebar group
+     * with that name is created.
+     */
+    parent?: string | undefined;
+};
+export type IrServer = {
+    url: string;
+    description?: string | undefined;
+};
+export type IrGroup = {
+    /** Stable slug used as the section anchor on the page. */
+    id: string;
+    /** Display name of the category. */
+    name: string;
+    /** Optional category description (Markdown). */
+    description?: string | undefined;
+    /** Operations belonging to this category. */
+    operations: IrOperation[];
+};
+export type IrOperation = {
+    /** Stable slug used as the operation's anchor on the page. */
+    id: string;
+    /** HTTP method (uppercased for display, e.g. `GET`). */
+    method: string;
+    /** Templated path (e.g. `/pets/{petId}`). */
+    path: string;
+    /**
+     * Name of the host operation's request example to preselect in the
+     * interactive client. Set for JSON-RPC operations expanded from an OpenRPC
+     * document (the JSON-RPC method name); lets "Try" prefill the right envelope
+     * even though every method shares the same path + verb.
+     */
+    rpcExample?: string | undefined;
+    summary?: string | undefined;
+    description?: string | undefined;
+    deprecated?: boolean | undefined;
+    /** Merged path-level + operation-level parameters. */
+    parameters: IrParameter[];
+    /** Request body (if any). */
+    requestBody?: IrBody | undefined;
+    /** Responses keyed by status code (e.g. `200`, `default`). */
+    responses: IrResponse[];
+    /** Security requirements that apply to this operation. */
+    security?: Record<string, string[]>[] | undefined;
+};
+export type IrParameter = {
+    name: string;
+    /**
+     * Where the parameter is supplied. `rpc` is a Vocs extension for JSON-RPC
+     * method params expanded from an OpenRPC document (rendered like query/path
+     * params but carried in the request body envelope).
+     */
+    in: 'path' | 'query' | 'header' | 'cookie' | 'rpc';
+    required?: boolean | undefined;
+    deprecated?: boolean | undefined;
+    description?: string | undefined;
+    /** Raw JSON Schema for the parameter value. */
+    schema?: Record<string, unknown> | undefined;
+    /** Example value provided at the parameter level. */
+    example?: unknown;
+};
+export type IrBody = {
+    required?: boolean | undefined;
+    description?: string | undefined;
+    /**
+     * Suppress the rendered "Request Body" section while still using the body to
+     * generate request code samples. Set for JSON-RPC operations expanded from an
+     * OpenRPC document, whose params are shown in a "Parameters" section instead.
+     */
+    hidden?: boolean | undefined;
+    /** Content keyed by media type (e.g. `application/json`). */
+    content: IrMediaType[];
+};
+export type IrMediaType = {
+    mediaType: string;
+    /** Raw JSON Schema for the media type. */
+    schema?: Record<string, unknown> | undefined;
+    /** Example value(s), if provided. */
+    example?: unknown;
+};
+export type IrResponse = {
+    /** Status code or `default`. */
+    status: string;
+    description?: string | undefined;
+    content: IrMediaType[];
+    /** Response headers, keyed by header name in the spec. */
+    headers: IrHeader[];
+};
+export type IrHeader = {
+    name: string;
+    required?: boolean | undefined;
+    deprecated?: boolean | undefined;
+    description?: string | undefined;
+    /** Raw JSON Schema for the header value. */
+    schema?: Record<string, unknown> | undefined;
+    /** Example value provided at the header level. */
+    example?: unknown;
+};
+export type IrSecurityScheme = Record<string, unknown> & {
+    type: string;
+    description?: string | undefined;
+};
+/**
+ * Parses an OpenAPI spec into the Vocs intermediate representation.
+ *
+ * Loads the spec (inline object, file path, raw content, or URL), upgrades it
+ * to OpenAPI 3.1, dereferences all `$ref`s, then groups operations into
+ * categories (by tag) for the sidebar and per-category pages.
+ */
+export declare function parse(config: OpenApi.Config, options?: parse.Options): Promise<Ir>;
+export declare namespace parse {
+    type Options = {
+        /** Directory file-path specs are resolved against. @default process.cwd() */
+        rootDir?: string | undefined;
+        /**
+         * Base URL relative `x-openrpc` URLs (e.g. `/openrpc.json`) resolve against
+         * when the spec itself wasn't loaded from a URL — the request origin in the
+         * standalone server handler.
+         */
+        baseUrl?: string | undefined;
+    };
+}
+//# sourceMappingURL=parser.d.ts.map

package/dist/internal/openapi/parser.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"parser.d.ts","sourceRoot":"","sources":["../../../src/internal/openapi/parser.ts"],"names":[],"mappings":"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"}

package/dist/internal/openapi/parser.js

@@ -0,0 +1,329 @@
+import { dereference, upgrade } from '@scalar/openapi-parser';
+import GithubSlugger from 'github-slugger';
+import * as OpenRpc from './openrpc.js';
+/**
+ * HTTP methods recognized on an OpenAPI path item, in canonical display order.
+ */
+export const methods = [
+    'get',
+    'post',
+    'put',
+    'patch',
+    'delete',
+    'head',
+    'options',
+    'trace',
+];
+/**
+ * Parses an OpenAPI spec into the Vocs intermediate representation.
+ *
+ * Loads the spec (inline object, file path, raw content, or URL), upgrades it
+ * to OpenAPI 3.1, dereferences all `$ref`s, then groups operations into
+ * categories (by tag) for the sidebar and per-category pages.
+ */
+export async function parse(config, options = {}) {
+    const { rootDir = typeof process !== 'undefined' ? process.cwd() : '.' } = options;
+    // Resolve a lazy provider or an already-started promise (e.g. a
+    // runtime-generated spec) to its value.
+    const input = typeof config.spec === 'function' ? config.spec() : config.spec;
+    const spec = await input;
+    const raw = await load(spec, rootDir);
+    const { specification } = upgrade(raw);
+    const { schema } = dereference(specification);
+    const document = (schema ?? specification);
+    const isUrl = typeof spec === 'string' && (spec.startsWith('http://') || spec.startsWith('https://'));
+    const specUrl = isUrl ? spec : undefined;
+    // Base for resolving relative `x-openrpc` URLs (e.g. `/openrpc.json`): the
+    // spec URL when the spec was loaded from a URL, else the caller-provided base
+    // (the request origin in the standalone server handler).
+    const openrpcBaseUrl = specUrl ?? options.baseUrl;
+    const servers = (document.servers ?? [])
+        .map((server) => ({
+        url: resolveServerUrl(server.url ?? '', specUrl),
+        description: server.description,
+    }))
+        .filter((server) => server.url);
+    const securitySchemes = document.components?.securitySchemes ?? {};
+    const { groups, injections } = await buildGroups(document, { baseUrl: openrpcBaseUrl });
+    // Inject JSON-RPC examples onto the host operation in the spec the
+    // interactive client loads, so each "Try" can preselect its method's
+    // envelope. The examples must live in the document Scalar reads; when the
+    // spec was a URL it would otherwise fetch the un-augmented version, so fall
+    // back to handing it the augmented `content` instead.
+    for (const injection of injections)
+        injectRpcExamples(specification, injection);
+    const client = isUrl && injections.length === 0
+        ? { url: spec }
+        : { content: specification };
+    return {
+        path: config.path ?? '/',
+        client,
+        info: {
+            title: document.info?.title ?? 'API Reference',
+            version: document.info?.version,
+            description: document.info?.description,
+        },
+        servers,
+        groups,
+        traits: buildTraits(document),
+        securitySchemes,
+    };
+}
+/**
+ * Adds named JSON-RPC request examples to a host operation's
+ * `application/json` request body in the (upgraded) spec document. Scalar
+ * builds one selectable request example per key, which the "Try" button
+ * navigates to via the operation's `rpcExample`.
+ */
+function injectRpcExamples(specification, injection) {
+    const paths = specification['paths'];
+    const operation = paths?.[injection.path]?.[injection.method];
+    if (!operation)
+        return;
+    let requestBody = operation['requestBody'];
+    // A `$ref`'d or absent body can't be merged in place; replace with an inline
+    // one carrying just the examples (the params already render in the docs).
+    if (!requestBody || typeof requestBody !== 'object' || '$ref' in requestBody) {
+        requestBody = {};
+        operation['requestBody'] = requestBody;
+    }
+    if (!requestBody['content'])
+        requestBody['content'] = {};
+    const content = requestBody['content'];
+    if (!content['application/json'])
+        content['application/json'] = {};
+    const media = content['application/json'];
+    media['examples'] = { ...media['examples'], ...injection.examples };
+}
+/** Builds doc-only "trait" pages from tags marked `x-traitTag: true`. */
+function buildTraits(document) {
+    const slugger = new GithubSlugger();
+    const traits = [];
+    for (const tag of document.tags ?? []) {
+        if (!tag.name || !tag['x-traitTag'])
+            continue;
+        traits.push({
+            id: slugger.slug(tag.name),
+            name: tag.name,
+            description: tag.description,
+            subtitle: tag['x-subtitle'],
+            parent: tag['x-parent'],
+        });
+    }
+    return traits;
+}
+/**
+ * Resolves a server URL to an absolute one.
+ *
+ * OpenAPI server URLs are often relative (e.g. `/` or `/v2`), meaning "relative
+ * to the host serving this document". When the spec was loaded from a URL we
+ * resolve such URLs against that origin (matching how Scalar and other tools
+ * behave) so generated code samples point at a real, callable host. Absolute
+ * URLs are returned untouched; relative URLs for file/inline specs are kept
+ * as-is. Any trailing slash is trimmed so callers can append paths directly.
+ */
+function resolveServerUrl(url, specUrl) {
+    if (!url)
+        return '';
+    if (/^https?:\/\//.test(url))
+        return url.replace(/\/$/, '');
+    if (!specUrl)
+        return url;
+    try {
+        return new URL(url, specUrl).toString().replace(/\/$/, '');
+    }
+    catch {
+        return url;
+    }
+}
+/** Resolves a spec input to a raw definition (object or string content). */
+async function load(spec, rootDir) {
+    if (typeof spec === 'object')
+        return spec;
+    if (spec.startsWith('http://') || spec.startsWith('https://')) {
+        const response = await fetch(spec);
+        if (!response.ok)
+            throw new Error(`Failed to fetch OpenAPI spec from ${spec}: ${response.statusText}`);
+        return response.text();
+    }
+    // Raw JSON/YAML content passed inline as a string — no filesystem needed.
+    // (Avoids importing `node:*` in non-Node runtimes like Cloudflare Workers,
+    // where local-file specs are unsupported anyway.)
+    if (looksLikeRawContent(spec))
+        return spec;
+    // Treat as a file path relative to rootDir; fall back to raw content. `node:*`
+    // is imported dynamically so URL/inline specs stay runtime-portable.
+    try {
+        const [{ default: fs }, path] = await Promise.all([
+            import('node:fs/promises').then((module) => ({ default: module })),
+            import('node:path'),
+        ]);
+        const filePath = path.isAbsolute(spec) ? spec : path.resolve(rootDir, spec);
+        return await fs.readFile(filePath, 'utf-8');
+    }
+    catch {
+        return spec;
+    }
+}
+/**
+ * Heuristic for raw inline spec content (vs. a file path): JSON starts with `{`,
+ * and a YAML document typically contains a newline or an `openapi:`/`swagger:`
+ * key. File paths are single-line and do not.
+ */
+function looksLikeRawContent(spec) {
+    const trimmed = spec.trimStart();
+    if (trimmed.startsWith('{'))
+        return true;
+    if (/\n/.test(spec) && /(^|\n)\s*(openapi|swagger)\s*:/.test(spec))
+        return true;
+    return false;
+}
+/** Groups operations by their first tag. */
+async function buildGroups(document, options = {}) {
+    const slugger = new GithubSlugger();
+    const order = [];
+    const byName = new Map();
+    const descriptions = new Map();
+    const injections = [];
+    // Seed group order from document-level `tags` so authoring order is preserved.
+    // Skip `x-traitTag` tags — they're doc-only pages, not operation categories.
+    for (const tag of document.tags ?? []) {
+        if (!tag.name || tag['x-traitTag'])
+            continue;
+        if (!byName.has(tag.name)) {
+            byName.set(tag.name, []);
+            order.push(tag.name);
+            descriptions.set(tag.name, tag.description);
+        }
+    }
+    const paths = document.paths ?? {};
+    for (const [pathname, item] of Object.entries(paths)) {
+        if (!item || typeof item !== 'object')
+            continue;
+        const pathParameters = item.parameters ?? [];
+        for (const method of methods) {
+            const operation = item[method];
+            if (!operation)
+                continue;
+            const groupName = operation.tags?.[0] ?? 'default';
+            if (!byName.has(groupName)) {
+                byName.set(groupName, []);
+                order.push(groupName);
+            }
+            const built = buildOperation({
+                method,
+                pathname,
+                operation,
+                pathParameters,
+                slugger,
+            });
+            // `x-openrpc` expands one operation into one operation per JSON-RPC method
+            // (each its own sidebar entry/section). On failure, fall back to the
+            // single host operation so the docs still render.
+            if (operation['x-openrpc']) {
+                try {
+                    const { operations, examples } = await OpenRpc.expand(built, operation['x-openrpc'], {
+                        baseUrl: options.baseUrl,
+                    });
+                    byName.get(groupName)?.push(...(operations.length > 0 ? operations : [built]));
+                    // Record the named JSON-RPC examples so the caller can inject them
+                    // onto the host operation in the spec handed to the interactive
+                    // client (Scalar selects the right one per "Try" click).
+                    if (operations.length > 0 && Object.keys(examples).length > 0)
+                        injections.push({ path: pathname, method, examples });
+                }
+                catch (error) {
+                    // Fall back to the single host operation so the docs still render, but
+                    // surface why the JSON-RPC methods are missing (e.g. a relative
+                    // `x-openrpc` URL with no base, or an unreachable document).
+                    console.warn(`[vocs] Failed to expand x-openrpc for ${method.toUpperCase()} ${pathname}: ${error instanceof Error ? error.message : String(error)}`);
+                    byName.get(groupName)?.push(built);
+                }
+            }
+            else {
+                byName.get(groupName)?.push(built);
+            }
+        }
+    }
+    const groups = order
+        .map((name) => ({
+        id: slugger.slug(name),
+        name,
+        description: descriptions.get(name),
+        operations: byName.get(name) ?? [],
+    }))
+        .filter((group) => group.operations.length > 0);
+    return { groups, injections };
+}
+function buildOperation(options) {
+    const { method, pathname, operation, pathParameters, slugger } = options;
+    const idSource = operation.operationId || `${method}-${pathname}`;
+    // Merge path-level parameters with operation-level (operation wins on conflict).
+    const merged = new Map();
+    for (const parameter of [...pathParameters, ...(operation.parameters ?? [])]) {
+        if (!parameter?.name || !parameter.in)
+            continue;
+        merged.set(`${parameter.in}:${parameter.name}`, parameter);
+    }
+    return {
+        id: slugger.slug(idSource),
+        method: method.toUpperCase(),
+        path: pathname,
+        summary: operation.summary,
+        description: operation.description,
+        deprecated: operation.deprecated,
+        parameters: [...merged.values()].map((parameter) => ({
+            name: parameter.name,
+            in: parameter.in,
+            required: parameter.required,
+            deprecated: parameter.deprecated,
+            description: parameter.description,
+            schema: parameter.schema,
+            example: parameter.example,
+        })),
+        requestBody: buildBody(operation.requestBody),
+        responses: buildResponses(operation.responses),
+        security: operation.security,
+    };
+}
+function buildBody(body) {
+    if (!body)
+        return undefined;
+    return {
+        required: body.required,
+        description: body.description,
+        content: buildContent(body.content),
+    };
+}
+function buildResponses(responses) {
+    if (!responses)
+        return [];
+    return Object.entries(responses).map(([status, response]) => ({
+        status,
+        description: response?.description,
+        content: buildContent(response?.content),
+        headers: buildHeaders(response?.headers),
+    }));
+}
+function buildHeaders(headers) {
+    if (!headers)
+        return [];
+    return Object.entries(headers).map(([name, header]) => ({
+        name,
+        required: header?.required,
+        deprecated: header?.deprecated,
+        description: header?.description,
+        schema: header?.schema,
+        example: header?.example,
+    }));
+}
+function buildContent(content) {
+    if (!content)
+        return [];
+    return Object.entries(content).map(([mediaType, value]) => ({
+        mediaType,
+        schema: value?.schema,
+        example: value?.example,
+    }));
+}
+//# sourceMappingURL=parser.js.map

package/dist/internal/openapi/parser.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"parser.js","sourceRoot":"","sources":["../../../src/internal/openapi/parser.ts"],"names":[],"mappings":"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"}

package/dist/internal/openapi/registry.d.ts

@@ -0,0 +1,36 @@
+import type { Config } from '../config.js';
+import type { SidebarItem } from '../sidebar.js';
+import { type Ir } from './parser.js';
+type Specs = Record<string, Ir>;
+/**
+ * Parses all configured OpenAPI specs into IRs, memoized across plugins and
+ * Vite environments. Call {@link invalidate} to force a re-parse (e.g. when a
+ * local spec file changes).
+ */
+export declare function build(config: Config): Promise<Specs>;
+/** Returns the cached specs, or `null` if not yet built. */
+export declare function peek(): Specs | null;
+/** Clears the cache so the next {@link build} re-parses. */
+export declare function invalidate(): void;
+/**
+ * Returns the OpenAPI-generated sidebars keyed by mount path, derived from the
+ * cached IRs. Empty if specs haven't been built yet or none are configured.
+ */
+export declare function sidebars(config?: Config): Record<string, {
+    backLink: boolean;
+    items: SidebarItem<true>[];
+}>;
+/**
+ * Merges OpenAPI-generated sidebars into a user's `sidebar` config.
+ *
+ * Returns the original config unchanged when no OpenAPI sidebars exist.
+ * Array-form sidebars are converted to path-keyed form (under `/`) so the
+ * OpenAPI section can be scoped to its own mount path.
+ *
+ * Per-entry `sidebar.top` / `sidebar.bottom` items (links to consumer guide
+ * pages mounted under the same path) are prepended/appended around the
+ * generated items. Never mutates inputs.
+ */
+export declare function mergeSidebar(config: Config): Config;
+export {};
+//# sourceMappingURL=registry.d.ts.map

package/dist/internal/openapi/registry.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"registry.d.ts","sourceRoot":"","sources":["../../../src/internal/openapi/registry.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,cAAc,CAAA;AAC1C,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,eAAe,CAAA;AAChD,OAAO,EAAE,KAAK,EAAE,EAAS,MAAM,aAAa,CAAA;AAG5C,KAAK,KAAK,GAAG,MAAM,CAAC,MAAM,EAAE,EAAE,CAAC,CAAA;AAK/B;;;;GAIG;AACH,wBAAsB,KAAK,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,KAAK,CAAC,CAc1D;AAED,4DAA4D;AAC5D,wBAAgB,IAAI,IAAI,KAAK,GAAG,IAAI,CAEnC;AAED,4DAA4D;AAC5D,wBAAgB,UAAU,IAAI,IAAI,CAGjC;AAED;;;GAGG;AACH,wBAAgB,QAAQ,CACtB,MAAM,CAAC,EAAE,MAAM,GACd,MAAM,CAAC,MAAM,EAAE;IAAE,QAAQ,EAAE,OAAO,CAAC;IAAC,KAAK,EAAE,WAAW,CAAC,IAAI,CAAC,EAAE,CAAA;CAAE,CAAC,CAQnE;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,YAAY,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,CAmBnD"}

package/dist/internal/openapi/registry.js

@@ -0,0 +1,79 @@
+import { parse } from './parser.js';
+import * as Sidebar from './sidebar.js';
+let cache = null;
+let building = null;
+/**
+ * Parses all configured OpenAPI specs into IRs, memoized across plugins and
+ * Vite environments. Call {@link invalidate} to force a re-parse (e.g. when a
+ * local spec file changes).
+ */
+export async function build(config) {
+    if (cache)
+        return cache;
+    if (building)
+        return building;
+    building = (async () => {
+        const next = {};
+        for (const entry of config.openapi ?? [])
+            next[entry.path] = await parse(entry, { rootDir: config.rootDir });
+        cache = next;
+        building = null;
+        return next;
+    })();
+    return building;
+}
+/** Returns the cached specs, or `null` if not yet built. */
+export function peek() {
+    return cache;
+}
+/** Clears the cache so the next {@link build} re-parses. */
+export function invalidate() {
+    cache = null;
+    building = null;
+}
+/**
+ * Returns the OpenAPI-generated sidebars keyed by mount path, derived from the
+ * cached IRs. Empty if specs haven't been built yet or none are configured.
+ */
+export function sidebars(config) {
+    const result = {};
+    if (!cache)
+        return result;
+    for (const [path, ir] of Object.entries(cache)) {
+        const collapsed = config?.openapi?.find((entry) => entry.path === path)?.sidebar?.collapsed;
+        result[path] = { backLink: true, items: Sidebar.toSidebar(ir, { collapsed }) };
+    }
+    return result;
+}
+/**
+ * Merges OpenAPI-generated sidebars into a user's `sidebar` config.
+ *
+ * Returns the original config unchanged when no OpenAPI sidebars exist.
+ * Array-form sidebars are converted to path-keyed form (under `/`) so the
+ * OpenAPI section can be scoped to its own mount path.
+ *
+ * Per-entry `sidebar.top` / `sidebar.bottom` items (links to consumer guide
+ * pages mounted under the same path) are prepended/appended around the
+ * generated items. Never mutates inputs.
+ */
+export function mergeSidebar(config) {
+    const generated = sidebars(config);
+    if (Object.keys(generated).length === 0)
+        return config;
+    const userSidebar = config.sidebar;
+    let merged;
+    if (!userSidebar)
+        merged = {};
+    else if (Array.isArray(userSidebar))
+        merged = { '/': userSidebar };
+    else
+        merged = { ...userSidebar };
+    for (const [path, sidebar] of Object.entries(generated)) {
+        const entry = config.openapi?.find((candidate) => candidate.path === path);
+        const top = entry?.sidebar?.top ?? [];
+        const bottom = entry?.sidebar?.bottom ?? [];
+        merged[path] = { ...sidebar, items: [...top, ...sidebar.items, ...bottom] };
+    }
+    return { ...config, sidebar: merged };
+}
+//# sourceMappingURL=registry.js.map

package/dist/internal/openapi/registry.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"registry.js","sourceRoot":"","sources":["../../../src/internal/openapi/registry.ts"],"names":[],"mappings":"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"}