@scalar/openapi-to-markdown 1.4.0 → 1.5.1

package/dist/render-document.js

@@ -1,117 +1,250 @@
+import { isObject } from '@scalar/helpers/object/is-object';
 import { forEachPathItemOperation, getResolvedPathItem, } from '@scalar/workspace-store/helpers/for-each-path-item-operation';
 import { getResolvedRef, mergeSiblingReferences } from '@scalar/workspace-store/helpers/get-resolved-ref';
 import remarkGfm from 'remark-gfm';
 import remarkStringify from 'remark-stringify';
 import { unified } from 'unified';
+import { anchor, createDocumentAnchors } from './document-anchors.js';
+import { createDocumentExamples } from './document-examples.js';
 import { field, heading, inlineCode, item, link, list, paragraph, strong, text } from './markdown-nodes.js';
-import { createDescriptionParser } from './parse-description.js';
+import { createDescriptionParser, expandDescriptions } from './parse-description.js';
 import { renderExamples } from './render-examples.js';
-import { renderOperation } from './render-operation.js';
+import { formatOperationMethod, renderOperation } from './render-operation.js';
 import { createSchemaRenderer } from './render-schema.js';
 import { renderSecurity } from './render-security.js';
-const serializer = unified().use(remarkGfm).use(remarkStringify, { bullet: '-' }).freeze();
+const serializer = unified()
+    .use(remarkGfm)
+    .use(remarkStringify, {
+    bullet: '-',
+    join: [
+        (left, right, parent) => {
+            if (!('spread' in parent))
+                return undefined;
+            // Inside a tight list item, content after a nested list would otherwise continue its last item.
+            if (left.type === 'list' && right.type !== 'list')
+                return 1;
+            // Code blocks in descriptions read better apart from the prose around them.
+            if (left.type === 'code' || right.type === 'code')
+                return 1;
+            return undefined;
+        },
+    ],
+})
+    .freeze();
+/** Authored values must survive even when the model does not generate an object example. */
+const hasAuthoredExamples = (view) => isObject(view.schema) &&
+    (view.schema.example !== undefined || (Array.isArray(view.schema.examples) && view.schema.examples.length > 0));
+/**
+ * Refer to a model that an operation or an earlier model on the same page already expanded.
+ * Keep what that expansion did not print: a title, and a description that a reference sibling replaced.
+ */
+const renderShownModel = async (name, view, previous, description) => {
+    const label = view.title && view.title !== name
+        ? [strong(text(view.title)), text(' ('), inlineCode(name), text(')')]
+        : [inlineCode(name)];
+    label.push(text(' — shown above'));
+    if (previous.name !== name)
+        label.push(text(' as '), inlineCode(previous.name));
+    label.push(text('.'));
+    const blocks = [paragraph(...label)];
+    if (view.description && view.description !== previous.description)
+        blocks.push(...(await description(view.description)));
+    return item(...blocks);
+};
 /** Build Markdown directly, retaining caches only for this immutable document snapshot. */
 export const createDocumentRenderer = () => {
     const descriptions = createDescriptionParser();
     const schemaRenderer = createSchemaRenderer();
-    return async (document, options) => {
+    return async (document, options = {}) => {
         const description = descriptions();
-        // Each page expands a shared schema once, then refers back to it.
-        const schemas = schemaRenderer.forDocument(document.components?.schemas, options);
-        const { info } = document;
-        const metadata = [
-            field('OpenAPI Version', inlineCode(document.openapi)),
-            field('API Version', inlineCode(info.version)),
-        ];
-        if (info.termsOfService)
-            metadata.push(field('Terms of service', link(info.termsOfService, info.termsOfService)));
-        if (info.contact) {
-            const contact = [text(info.contact.name ?? '')];
-            metadata.push(item(paragraph(strong(text('Contact:')), text(' '), ...contact, ...(info.contact.url ? [text(' '), link(info.contact.url, info.contact.url)] : []), ...(info.contact.email ? [text(' '), link(`mailto:${info.contact.email}`, info.contact.email)] : []))));
-        }
-        if (info.license)
-            metadata.push(field('License', info.license.url ? link(info.license.url, info.license.name ?? '') : text(info.license.name)));
-        const nodes = [
-            heading(1, text(info.title)),
-            list(metadata),
-            ...(await description(info.description)),
-        ];
-        if (document.servers?.length) {
-            nodes.push(heading(2, text('Servers')));
-            const servers = document.servers.map((server) => {
-                const nested = [];
-                if (server.description)
-                    nested.push(field('Description', text(server.description)));
-                const variables = Object.entries(server.variables ?? {});
-                if (variables.length)
-                    nested.push(item(paragraph(strong(text('Variables:'))), list(variables.map(([name, variable]) => item(paragraph(inlineCode(name), text(' (default: '), inlineCode(variable.default), text(`)${variable.description ? `: ${variable.description}` : ''}`)))))));
-                const entry = field('URL', inlineCode(server.url));
-                if (nested.length)
-                    entry.children.push(list(nested));
-                return entry;
-            });
-            nodes.push(list(servers));
-        }
-        nodes.push(...(await renderSecurity(document.security, document.components?.securitySchemes, description)));
-        if (document.tags?.length) {
-            nodes.push(heading(2, text('Tags')));
-            for (const tag of document.tags) {
-                nodes.push(heading(3, text(tag.name)), ...(await description(tag.description)));
-                if (tag.externalDocs)
-                    nodes.push(paragraph(link(tag.externalDocs.url, tag.externalDocs.description ?? tag.externalDocs.url)));
+        const whole = [options.operation, options.webhook, options.model, options.tag, options.introduction].every((selector) => selector === undefined);
+        const anchors = createDocumentAnchors();
+        const examples = whole ? createDocumentExamples(anchors) : undefined;
+        const documentContext = whole
+            ? {
+                anchors,
+                servers: document.servers !== undefined ? anchors.get('context', 'global-servers') : undefined,
+                authentication: document.security !== undefined ? anchors.get('context', 'global-authentication') : undefined,
+                pathServers: new WeakMap(),
             }
-        }
-        const sections = [];
-        const flush = () => {
-            if (nodes.length) {
-                const tree = { type: 'root', children: nodes.splice(0) };
-                sections.push(serializer.stringify(tree).trimEnd());
-            }
-        };
-        flush();
-        for (const group of [
+            : undefined;
+        const destinations = whole
+            ? new Map(Object.keys(document.components?.schemas ?? {}).map((name) => [
+                name,
+                `#${encodeURIComponent(anchors.get('schema', name))}`,
+            ]))
+            : undefined;
+        const groups = [
             { title: 'Operations', paths: document.paths, webhook: false },
             { title: 'Webhooks', paths: document.webhooks, webhook: true },
-        ]) {
-            let hasOperations = false;
+        ].map((group) => {
+            const entries = [];
             for (const [path, reference] of Object.entries(group.paths ?? {})) {
                 const pathItem = getResolvedPathItem(reference);
                 if (!pathItem)
                     continue;
-                const entries = [];
                 forEachPathItemOperation(reference, (method, operation) => {
-                    entries.push({ method, operation: getResolvedRef(operation, mergeSiblingReferences) });
+                    const label = `${formatOperationMethod(method)} ${path}`;
+                    entries.push({
+                        path,
+                        method,
+                        pathItem,
+                        operation: getResolvedRef(operation, mergeSiblingReferences),
+                        label,
+                        id: whole
+                            ? anchors.get(group.webhook ? 'webhook' : 'operation', JSON.stringify([path, method]), label)
+                            : undefined,
+                    });
                 });
-                for (const { method, operation } of entries) {
-                    if (!hasOperations) {
-                        nodes.push(heading(2, text(group.title)));
-                        hasOperations = true;
-                    }
-                    schemas.beginSection();
-                    nodes.push(...(await renderOperation(document, path, method, pathItem, operation, group.webhook, {
-                        description,
-                        schemas,
-                    })));
-                    flush();
+            }
+            return { ...group, entries };
+        });
+        // Each page expands a shared schema once, then refers back to it.
+        const schemas = schemaRenderer.forDocument(document.components?.schemas, options, destinations);
+        const openapiVersion = document['x-original-oas-version'] ?? document.openapi;
+        // A page for one operation, webhook or model starts with that item, not with the API.
+        const single = options.operation !== undefined || options.webhook !== undefined || options.model !== undefined;
+        const nodes = [];
+        const sections = [];
+        const flush = async () => {
+            if (!nodes.length)
+                return;
+            const children = nodes.splice(0);
+            await expandDescriptions(children, description);
+            sections.push(serializer.stringify({ type: 'root', children }).trimEnd());
+        };
+        if (!single) {
+            const { info } = document;
+            const metadata = [field('OpenAPI Version', inlineCode(document.openapi))];
+            if (info.version)
+                metadata.push(field('API Version', inlineCode(info.version)));
+            if (info.termsOfService)
+                metadata.push(field('Terms of service', link(info.termsOfService, info.termsOfService)));
+            if (info.contact) {
+                const contact = [text(info.contact.name ?? '')];
+                metadata.push(item(paragraph(strong(text('Contact:')), text(' '), ...contact, ...(info.contact.url ? [text(' '), link(info.contact.url, info.contact.url)] : []), ...(info.contact.email ? [text(' '), link(`mailto:${info.contact.email}`, info.contact.email)] : []))));
+            }
+            if (info.license)
+                metadata.push(field('License', info.license.url ? link(info.license.url, info.license.name ?? '') : text(info.license.name)));
+            nodes.push(heading(1, text(info.title)), list(metadata), ...(await description(info.description)));
+            if (whole) {
+                const contents = [];
+                for (const group of groups) {
+                    if (!group.entries.length)
+                        continue;
+                    contents.push(paragraph(strong(text(group.title))), list(group.entries.map(({ id, label }) => item(paragraph(link(`#${encodeURIComponent(id)}`, label))))));
+                }
+                if (destinations?.size) {
+                    contents.push(paragraph(strong(text('Schemas'))), list([...destinations].map(([name, url]) => item(paragraph(link(url, name))))));
                 }
+                if (contents.length)
+                    nodes.push(heading(2, text('Contents')), ...contents);
+            }
+            if (document.servers?.length || (whole && document.servers !== undefined)) {
+                if (documentContext?.servers)
+                    nodes.push(anchor(documentContext.servers));
+                nodes.push(heading(2, text('Servers')));
+                const effectiveServers = document.servers?.length
+                    ? document.servers
+                    : [{ url: '/' }];
+                const servers = effectiveServers.map((server) => {
+                    const nested = [];
+                    if (server.description)
+                        nested.push(field('Description', text(server.description)));
+                    const variables = Object.entries(server.variables ?? {});
+                    if (variables.length)
+                        nested.push(item(paragraph(strong(text('Variables:'))), list(variables.map(([name, variable]) => item(paragraph(inlineCode(name), text(' (default: '), inlineCode(variable.default), text(')'), ...(whole && variable.enum?.length
+                            ? [text(', possible values: '), inlineCode(variable.enum.join(', '))]
+                            : []), text(variable.description ? `: ${variable.description}` : '')))))));
+                    const entry = field('URL', inlineCode(server.url));
+                    if (nested.length)
+                        entry.children.push(list(nested));
+                    return entry;
+                });
+                nodes.push(list(servers));
+            }
+            if (documentContext?.authentication)
+                nodes.push(anchor(documentContext.authentication));
+            nodes.push(...(await renderSecurity(document.security, document.components?.securitySchemes, description, 2)));
+            if (document.tags?.length) {
+                nodes.push(heading(2, text('Tags')));
+                for (const tag of document.tags) {
+                    nodes.push(heading(3, text(tag.name)), ...(await description(tag.description)));
+                    if (tag.externalDocs)
+                        nodes.push(paragraph(link(tag.externalDocs.url, tag.externalDocs.description ?? tag.externalDocs.url)));
+                }
+            }
+            await flush();
+        }
+        for (const group of groups) {
+            let hasOperations = false;
+            for (const { path, pathItem, method, operation, id } of group.entries) {
+                if (!hasOperations && !single)
+                    nodes.push(heading(2, text(group.title)));
+                hasOperations = true;
+                schemas.beginSection();
+                if (id)
+                    nodes.push(anchor(id));
+                nodes.push(...(await renderOperation(document, path, method, pathItem, operation, group.webhook, {
+                    description,
+                    schemas,
+                    examples,
+                    documentContext,
+                    level: single ? 1 : 3,
+                })));
+                await flush();
             }
         }
-        const models = Object.entries(document.components?.schemas ?? {});
-        if (models.length)
+        // A model page renders its own model first, as the page title.
+        const models = Object.entries(document.components?.schemas ?? {}).sort(([a], [b]) => Number(b === options.model) - Number(a === options.model));
+        const renderModel = async (name, schema, level) => {
+            const view = schemas.view(schema);
+            const summary = schemas.summarize(schema);
+            if (whole)
+                nodes.push(anchor(anchors.get('schema', name)));
+            nodes.push(heading(level, text(view.title ?? name)));
+            if (summary.length)
+                nodes.push(paragraph(strong(text('Type:')), text('\u00a0'), ...summary));
+            nodes.push(...(await description(view.description)), ...schemas.render(schema, 0, [], { hideDetails: true, name }));
+            if (view.type === 'object' || hasAuthoredExamples(view)) {
+                // A model page's own schema is bounded, so it gets a generated example even in linked mode.
+                const own = name === options.model;
+                nodes.push(...(await renderExamples({ schema: own ? schemas.exampleSchema(schema) : schema }, description, 'application/json', undefined, openapiVersion, document.openapi, {
+                    linked: schemas.linked && !own,
+                    quiet: schemas.linked,
+                    examples,
+                })));
+            }
+            await flush();
+        };
+        const selected = models.find(([name]) => name === options.model);
+        if (selected) {
+            schemas.beginSection();
+            await renderModel(selected[0], selected[1], 1);
+        }
+        const dependencies = models.filter(([name]) => name !== options.model);
+        if (dependencies.length)
             nodes.push(heading(2, text('Schemas')));
-        for (const [name, schema] of models) {
+        // Models the page already expanded cost one line each, grouped into a single list.
+        const shownAbove = [];
+        const flushShownAbove = () => {
+            if (shownAbove.length)
+                nodes.push(list(shownAbove.splice(0)));
+        };
+        for (const [name, schema] of dependencies) {
             schemas.beginSection();
             const view = schemas.view(schema);
-            nodes.push(heading(3, text(view.title ?? name)), list([
-                view.type
-                    ? field('Type', inlineCode(Array.isArray(view.type) ? view.type.join(' | ') : view.type))
-                    : item(paragraph(strong(text('Type:')))),
-            ]), ...(await description(view.description)), ...schemas.render(schema, 0, [], { hideDescription: true, name }));
-            if (view.type === 'object')
-                nodes.push(...(await renderExamples({ schema }, description, 'application/json', undefined, document['x-original-oas-version'] ?? document.openapi, document.openapi, schemas.linked)));
-            flush();
+            const previous = schemas.shownAs(schema);
+            // A generated example only restates the schema, but an authored one is not printed above.
+            if (!whole && previous && !hasAuthoredExamples(view)) {
+                shownAbove.push(await renderShownModel(name, view, previous, description));
+                continue;
+            }
+            flushShownAbove();
+            await renderModel(name, schema, 3);
         }
-        flush();
+        flushShownAbove();
+        await flush();
         return `${sections.join('\n\n')}\n`;
     };
 };

package/dist/render-examples.d.ts

@@ -1,6 +1,14 @@
 import type { RootContent } from 'mdast';
+import type { DocumentExamples } from './document-examples.js';
 import { type ExampleSource } from './get-markdown-examples.js';
 import type { DescriptionParser } from './parse-description.js';
 /** Render supplied examples before considering a schema-generated fallback. */
-export declare const renderExamples: (source: ExampleSource, description: DescriptionParser, mediaType?: string, mode?: "read" | "write", openapiVersion?: string, schemaOpenapiVersion?: string, linked?: boolean) => Promise<RootContent[]>;
+export declare const renderExamples: (source: ExampleSource, description: DescriptionParser, mediaType?: string, mode?: "read" | "write", openapiVersion?: string, schemaOpenapiVersion?: string, { linked, quiet, examples, }?: {
+    /** Use only authored examples, since generating one would expand every linked schema. */
+    linked?: boolean;
+    /** Leave out an example that is too large to generate, instead of noting it. */
+    quiet?: boolean;
+    /** A whole document shares generation and links to identical generated examples. */
+    examples?: DocumentExamples;
+}) => Promise<RootContent[]>;
 //# sourceMappingURL=render-examples.d.ts.map

package/dist/render-examples.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"render-examples.d.ts","sourceRoot":"","sources":["../src/render-examples.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,OAAO,CAAA;AAExC,OAAO,EAAE,KAAK,aAAa,EAAuB,MAAM,yBAAyB,CAAA;AAEjF,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,qBAAqB,CAAA;AAE5D,+EAA+E;AAC/E,eAAO,MAAM,cAAc,GACzB,QAAQ,aAAa,EACrB,aAAa,iBAAiB,EAC9B,kBAA8B,EAC9B,OAAO,MAAM,GAAG,OAAO,EACvB,uBAAwB,EAExB,6BAAqC,EACrC,gBAAc,KACb,OAAO,CAAC,WAAW,EAAE,CAyDvB,CAAA"}
+{"version":3,"file":"render-examples.d.ts","sourceRoot":"","sources":["../src/render-examples.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAQ,WAAW,EAAE,MAAM,OAAO,CAAA;AAG9C,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,qBAAqB,CAAA;AAC3D,OAAO,EAAE,KAAK,aAAa,EAAuB,MAAM,yBAAyB,CAAA;AAEjF,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,qBAAqB,CAAA;AAE5D,+EAA+E;AAC/E,eAAO,MAAM,cAAc,GACzB,QAAQ,aAAa,EACrB,aAAa,iBAAiB,EAC9B,kBAA8B,EAC9B,OAAO,MAAM,GAAG,OAAO,EACvB,uBAAwB,EAExB,6BAAqC,EACrC,+BAIG;IACD,yFAAyF;IACzF,MAAM,CAAC,EAAE,OAAO,CAAA;IAChB,gFAAgF;IAChF,KAAK,CAAC,EAAE,OAAO,CAAA;IACf,oFAAoF;IACpF,QAAQ,CAAC,EAAE,gBAAgB,CAAA;CACvB,KACL,OAAO,CAAC,WAAW,EAAE,CA8EvB,CAAA"}

package/dist/render-examples.js

@@ -1,16 +1,34 @@
 import { isXmlMediaType } from '@scalar/helpers/http/is-xml-media-type';
 import { getXmlBodyExample } from '@scalar/workspace-store/request-example';
+import { anchor } from './document-anchors.js';
 import { getMarkdownExamples } from './get-markdown-examples.js';
-import { link, paragraph, strong, text } from './markdown-nodes.js';
+import { emphasis, link, paragraph, strong, text } from './markdown-nodes.js';
 /** Render supplied examples before considering a schema-generated fallback. */
 export const renderExamples = async (source, description, mediaType = 'application/json', mode, openapiVersion = '3.2.0', 
 // Schema metadata can be upgraded while example fields still follow the original version.
-schemaOpenapiVersion = openapiVersion, linked = false) => {
+schemaOpenapiVersion = openapiVersion, { linked = false, quiet = linked, examples, } = {}) => {
     const nodes = [];
-    for (const example of getMarkdownExamples(source, mediaType, mode, openapiVersion, schemaOpenapiVersion, linked)) {
-        nodes.push(paragraph(strong(text(example.name ? `Example: ${example.name}` : 'Example:'))));
+    const values = (examples?.get ?? getMarkdownExamples)(source, mediaType, mode, openapiVersion, schemaOpenapiVersion, linked);
+    for (const example of values) {
+        if ('omitted' in example && quiet)
+            continue;
+        const start = nodes.length;
+        const generated = examples && example.generated;
+        nodes.push(paragraph(strong(text(generated ? 'Generated example:' : example.name ? `Example: ${example.name}` : 'Example:'))));
+        const addCode = (code) => {
+            if (generated) {
+                const scope = JSON.stringify([mediaType, mode, openapiVersion, schemaOpenapiVersion, code.lang]);
+                const destination = examples.show(source, scope, code);
+                if (destination.previous) {
+                    nodes.splice(start, nodes.length - start, paragraph(link(`#${destination.id}`, 'Generated example')));
+                    return;
+                }
+                nodes.splice(start, 0, anchor(destination.id));
+            }
+            nodes.push(code);
+        };
         if ('omitted' in example) {
-            nodes.push(paragraph(text(`${linked ? '[Generated example omitted in linked schema mode; see the schema documentation]' : '[Generated example omitted because it is too large]'}`)));
+            nodes.push(paragraph(emphasis(text('Generated example omitted because it is too large.'))));
             continue;
         }
         if (example.summary)
@@ -25,7 +43,7 @@ schemaOpenapiVersion = openapiVersion, linked = false) => {
             continue;
         }
         if ('serializedValue' in example) {
-            nodes.push({
+            addCode({
                 type: 'code',
                 lang: isXmlMediaType(mediaType) ? 'xml' : mediaType.includes('json') ? 'json' : 'text',
                 value: example.serializedValue,
@@ -35,7 +53,7 @@ schemaOpenapiVersion = openapiVersion, linked = false) => {
         const xml = isXmlMediaType(mediaType);
         const value = 'dataValue' in example ? example.dataValue : example.value;
         if (xml && !source.schema && 'value' in example && (value === null || typeof value !== 'object')) {
-            nodes.push({ type: 'code', lang: 'xml', value: String(value) });
+            addCode({ type: 'code', lang: 'xml', value: String(value) });
             continue;
         }
         const result = xml
@@ -48,7 +66,7 @@ schemaOpenapiVersion = openapiVersion, linked = false) => {
             nodes.push(paragraph(text('Unable to generate an XML example.')));
             continue;
         }
-        nodes.push({
+        addCode({
             type: 'code',
             lang: xml ? 'xml' : 'json',
             value: result?.xml ?? JSON.stringify(value, null, 2) ?? '',

package/dist/render-operation-details.d.ts

@@ -1,11 +1,12 @@
 import type { EncodingObject, ResponseObject } from '@scalar/workspace-store/schemas/v3.2/strict/openapi-document';
 import type { RootContent } from 'mdast';
+import type { DocumentExamples } from './document-examples.js';
 import type { DescriptionParser } from './parse-description.js';
 import type { SchemaRenderer } from './render-schema.js';
 /** Render response or multipart headers, whose names come from their containing map. */
-export declare const renderHeaders: (headers: ResponseObject["headers"], description: DescriptionParser, schemas: SchemaRenderer, openapiVersion: string, schemaOpenapiVersion?: string) => Promise<RootContent[]>;
+export declare const renderHeaders: (headers: ResponseObject["headers"], description: DescriptionParser, schemas: SchemaRenderer, openapiVersion: string, schemaOpenapiVersion?: string, examples?: DocumentExamples) => Promise<RootContent[]>;
 /** Preserve explicit encoding settings, including false flags and part headers. */
-export declare const renderEncoding: (encoding: Record<string, EncodingObject> | undefined, mediaType: string, description: DescriptionParser, schemas: SchemaRenderer, openapiVersion: string, schemaOpenapiVersion?: string) => Promise<RootContent[]>;
+export declare const renderEncoding: (encoding: Record<string, EncodingObject> | undefined, mediaType: string, description: DescriptionParser, schemas: SchemaRenderer, openapiVersion: string, schemaOpenapiVersion?: string, examples?: DocumentExamples) => Promise<RootContent[]>;
 /** Render response link expressions as literal values, without evaluating them. */
 export declare const renderResponseLinks: (links: ResponseObject["links"], description: DescriptionParser) => Promise<RootContent[]>;
 //# sourceMappingURL=render-operation-details.d.ts.map

package/dist/render-operation-details.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"render-operation-details.d.ts","sourceRoot":"","sources":["../src/render-operation-details.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,cAAc,EAAE,cAAc,EAAE,MAAM,8DAA8D,CAAA;AAClH,OAAO,KAAK,EAAY,WAAW,EAAE,MAAM,OAAO,CAAA;AAGlD,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,qBAAqB,CAAA;AAE5D,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,iBAAiB,CAAA;AAErD,wFAAwF;AACxF,eAAO,MAAM,aAAa,GACxB,SAAS,cAAc,CAAC,SAAS,CAAC,EAClC,aAAa,iBAAiB,EAC9B,SAAS,cAAc,EACvB,gBAAgB,MAAM,EACtB,6BAAqC,KACpC,OAAO,CAAC,WAAW,EAAE,CA4CvB,CAAA;AAED,mFAAmF;AACnF,eAAO,MAAM,cAAc,GACzB,UAAU,MAAM,CAAC,MAAM,EAAE,cAAc,CAAC,GAAG,SAAS,EACpD,WAAW,MAAM,EACjB,aAAa,iBAAiB,EAC9B,SAAS,cAAc,EACvB,gBAAgB,MAAM,EACtB,6BAAqC,KACpC,OAAO,CAAC,WAAW,EAAE,CA6BvB,CAAA;AAID,mFAAmF;AACnF,eAAO,MAAM,mBAAmB,GAC9B,OAAO,cAAc,CAAC,OAAO,CAAC,EAC9B,aAAa,iBAAiB,KAC7B,OAAO,CAAC,WAAW,EAAE,CA2BvB,CAAA"}
+{"version":3,"file":"render-operation-details.d.ts","sourceRoot":"","sources":["../src/render-operation-details.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,cAAc,EAAE,cAAc,EAAE,MAAM,8DAA8D,CAAA;AAClH,OAAO,KAAK,EAAY,WAAW,EAAE,MAAM,OAAO,CAAA;AAElD,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,qBAAqB,CAAA;AAE3D,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,qBAAqB,CAAA;AAE5D,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,iBAAiB,CAAA;AAErD,wFAAwF;AACxF,eAAO,MAAM,aAAa,GACxB,SAAS,cAAc,CAAC,SAAS,CAAC,EAClC,aAAa,iBAAiB,EAC9B,SAAS,cAAc,EACvB,gBAAgB,MAAM,EACtB,6BAAqC,EACrC,WAAW,gBAAgB,KAC1B,OAAO,CAAC,WAAW,EAAE,CAuCvB,CAAA;AAED,mFAAmF;AACnF,eAAO,MAAM,cAAc,GACzB,UAAU,MAAM,CAAC,MAAM,EAAE,cAAc,CAAC,GAAG,SAAS,EACpD,WAAW,MAAM,EACjB,aAAa,iBAAiB,EAC9B,SAAS,cAAc,EACvB,gBAAgB,MAAM,EACtB,6BAAqC,EACrC,WAAW,gBAAgB,KAC1B,OAAO,CAAC,WAAW,EAAE,CA8BvB,CAAA;AAID,mFAAmF;AACnF,eAAO,MAAM,mBAAmB,GAC9B,OAAO,cAAc,CAAC,OAAO,CAAC,EAC9B,aAAa,iBAAiB,KAC7B,OAAO,CAAC,WAAW,EAAE,CA2BvB,CAAA"}

package/dist/render-operation-details.js

@@ -2,7 +2,7 @@ import { getResolvedRef, mergeSiblingReferences } from '@scalar/workspace-store/
 import { inlineCode, item, list, paragraph, strong, text } from './markdown-nodes.js';
 import { renderExamples } from './render-examples.js';
 /** Render response or multipart headers, whose names come from their containing map. */
-export const renderHeaders = async (headers, description, schemas, openapiVersion, schemaOpenapiVersion = openapiVersion) => {
+export const renderHeaders = async (headers, description, schemas, openapiVersion, schemaOpenapiVersion = openapiVersion, examples) => {
     const entries = [];
     for (const [name, reference] of Object.entries(headers ?? {})) {
         // OpenAPI reserves Content-Type for the media type map / encoding field.
@@ -18,20 +18,23 @@ export const renderHeaders = async (headers, description, schemas, openapiVersio
         if ('schema' in header && header.schema !== undefined)
             blocks.push(...schemas.render(header.schema));
         if ('example' in header || 'examples' in header) {
-            blocks.push(...(await renderExamples({ example: header.example, examples: header.examples }, description, 'application/json', undefined, openapiVersion, schemaOpenapiVersion, schemas.linked)));
+            blocks.push(...(await renderExamples({ example: header.example, examples: header.examples }, description, 'application/json', undefined, openapiVersion, schemaOpenapiVersion, { linked: schemas.linked, examples })));
         }
         for (const [mediaType, content] of Object.entries('content' in header ? (header.content ?? {}) : {})) {
             blocks.push(paragraph(strong(text('Content-Type:')), text(` ${mediaType}`)));
             if (content.schema !== undefined)
                 blocks.push(...schemas.render(content.schema));
-            blocks.push(...(await renderExamples(content, description, mediaType, undefined, openapiVersion, schemaOpenapiVersion, schemas.linked)));
+            blocks.push(...(await renderExamples(content, description, mediaType, undefined, openapiVersion, schemaOpenapiVersion, {
+                linked: schemas.linked,
+                examples,
+            })));
         }
         entries.push(item(...blocks));
     }
     return entries.length ? [paragraph(strong(text('Headers:'))), list(entries)] : [];
 };
 /** Preserve explicit encoding settings, including false flags and part headers. */
-export const renderEncoding = async (encoding, mediaType, description, schemas, openapiVersion, schemaOpenapiVersion = openapiVersion) => {
+export const renderEncoding = async (encoding, mediaType, description, schemas, openapiVersion, schemaOpenapiVersion = openapiVersion, examples) => {
     const multipart = mediaType.startsWith('multipart/');
     if (!multipart && mediaType !== 'application/x-www-form-urlencoded')
         return [];
@@ -51,7 +54,7 @@ export const renderEncoding = async (encoding, mediaType, description, schemas,
         if (fields.length)
             blocks.push(list(fields));
         if (multipart)
-            blocks.push(...(await renderHeaders(entry.headers, description, schemas, openapiVersion, schemaOpenapiVersion)));
+            blocks.push(...(await renderHeaders(entry.headers, description, schemas, openapiVersion, schemaOpenapiVersion, examples)));
         entries.push(item(...blocks));
     }
     return entries.length ? [paragraph(strong(text('Encoding:'))), list(entries)] : [];

package/dist/render-operation.d.ts

@@ -1,13 +1,28 @@
 import type { OpenApiDocument, OperationObject, PathItemObject } from '@scalar/workspace-store/schemas/v3.2/strict/openapi-document';
 import type { RootContent } from 'mdast';
+import { type createDocumentAnchors } from './document-anchors.js';
+import type { DocumentExamples } from './document-examples.js';
 import type { DescriptionParser } from './parse-description.js';
 import type { SchemaRenderer } from './render-schema.js';
 /** Dependencies shared by all sections of one prepared renderer. */
 type RenderContext = {
     description: DescriptionParser;
     schemas: SchemaRenderer;
+    examples?: DocumentExamples;
+    documentContext?: DocumentContext;
+    /** The heading level of the operation title: 1 on its own page, 3 inside a document. */
+    level?: number;
 };
+/** Destinations for defaults that a whole document explains once. */
+export type DocumentContext = {
+    anchors: ReturnType<typeof createDocumentAnchors>;
+    servers?: string;
+    authentication?: string;
+    pathServers: WeakMap<object, string>;
+};
+/** Format standard HTTP methods while preserving custom method names. */
+export declare const formatOperationMethod: (method: string) => string;
 /** Render effective operation context without mutating the prepared document. */
-export declare const renderOperation: (document: OpenApiDocument, path: string, method: string, pathItem: PathItemObject, operation: OperationObject, webhook: boolean, { description, schemas }: RenderContext) => Promise<RootContent[]>;
+export declare const renderOperation: (document: OpenApiDocument, path: string, method: string, pathItem: PathItemObject, operation: OperationObject, webhook: boolean, { description, schemas, examples, documentContext, level }: RenderContext) => Promise<RootContent[]>;
 export {};
 //# sourceMappingURL=render-operation.d.ts.map

package/dist/render-operation.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"render-operation.d.ts","sourceRoot":"","sources":["../src/render-operation.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EACV,eAAe,EACf,eAAe,EAEf,cAAc,EAGf,MAAM,8DAA8D,CAAA;AACrE,OAAO,KAAK,EAAY,WAAW,EAAE,MAAM,OAAO,CAAA;AAGlD,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,qBAAqB,CAAA;AAG5D,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,iBAAiB,CAAA;AAGrD,oEAAoE;AACpE,KAAK,aAAa,GAAG;IACnB,WAAW,EAAE,iBAAiB,CAAA;IAC9B,OAAO,EAAE,cAAc,CAAA;CACxB,CAAA;AAED,iFAAiF;AACjF,eAAO,MAAM,eAAe,GAC1B,UAAU,eAAe,EACzB,MAAM,MAAM,EACZ,QAAQ,MAAM,EACd,UAAU,cAAc,EACxB,WAAW,eAAe,EAC1B,SAAS,OAAO,EAChB,0BAA0B,aAAa,KACtC,OAAO,CAAC,WAAW,EAAE,CA0IvB,CAAA"}
+{"version":3,"file":"render-operation.d.ts","sourceRoot":"","sources":["../src/render-operation.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EACV,eAAe,EACf,eAAe,EAEf,cAAc,EAGf,MAAM,8DAA8D,CAAA;AACrE,OAAO,KAAK,EAAsC,WAAW,EAAE,MAAM,OAAO,CAAA;AAE5E,OAAO,EAAU,KAAK,qBAAqB,EAAE,MAAM,oBAAoB,CAAA;AACvE,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,qBAAqB,CAAA;AAE3D,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,qBAAqB,CAAA;AAG5D,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,iBAAiB,CAAA;AAGrD,oEAAoE;AACpE,KAAK,aAAa,GAAG;IACnB,WAAW,EAAE,iBAAiB,CAAA;IAC9B,OAAO,EAAE,cAAc,CAAA;IACvB,QAAQ,CAAC,EAAE,gBAAgB,CAAA;IAC3B,eAAe,CAAC,EAAE,eAAe,CAAA;IACjC,wFAAwF;IACxF,KAAK,CAAC,EAAE,MAAM,CAAA;CACf,CAAA;AAED,qEAAqE;AACrE,MAAM,MAAM,eAAe,GAAG;IAC5B,OAAO,EAAE,UAAU,CAAC,OAAO,qBAAqB,CAAC,CAAA;IACjD,OAAO,CAAC,EAAE,MAAM,CAAA;IAChB,cAAc,CAAC,EAAE,MAAM,CAAA;IACvB,WAAW,EAAE,OAAO,CAAC,MAAM,EAAE,MAAM,CAAC,CAAA;CACrC,CAAA;AAoCD,yEAAyE;AACzE,eAAO,MAAM,qBAAqB,GAAI,QAAQ,MAAM,KAAG,MACkC,CAAA;AAEzF,iFAAiF;AACjF,eAAO,MAAM,eAAe,GAC1B,UAAU,eAAe,EACzB,MAAM,MAAM,EACZ,QAAQ,MAAM,EACd,UAAU,cAAc,EACxB,WAAW,eAAe,EAC1B,SAAS,OAAO,EAChB,4DAAgE,aAAa,KAC5E,OAAO,CAAC,WAAW,EAAE,CAiLvB,CAAA"}