@scalar/openapi-to-markdown 1.3.0 → 1.5.0

package/dist/render-security.d.ts

@@ -1,6 +1,10 @@
 import type { OpenApiDocument } from '@scalar/workspace-store/schemas/v3.2/strict/openapi-document';
-import type { RootContent } from 'mdast';
+import type { Heading, RootContent } from 'mdast';
 import type { DescriptionParser } from './parse-description.js';
-/** Preserve OR between requirements and AND between schemes within a requirement. */
-export declare const renderSecurity: (requirements: OpenApiDocument["security"], schemes: NonNullable<OpenApiDocument["components"]>["securitySchemes"], description: DescriptionParser) => Promise<RootContent[]>;
+/**
+ * Preserve OR between requirements and AND between schemes within a requirement.
+ * Without declared requirements there is nothing to say: only an explicit empty list means that
+ * no authentication is required.
+ */
+export declare const renderSecurity: (requirements: OpenApiDocument["security"], schemes: NonNullable<OpenApiDocument["components"]>["securitySchemes"], description: DescriptionParser, level?: Heading["depth"]) => Promise<RootContent[]>;
 //# sourceMappingURL=render-security.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"render-security.d.ts","sourceRoot":"","sources":["../src/render-security.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,8DAA8D,CAAA;AACnG,OAAO,KAAK,EAAY,WAAW,EAAE,MAAM,OAAO,CAAA;AAGlD,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,qBAAqB,CAAA;AAE5D,qFAAqF;AACrF,eAAO,MAAM,cAAc,GACzB,cAAc,eAAe,CAAC,UAAU,CAAC,EACzC,SAAS,WAAW,CAAC,eAAe,CAAC,YAAY,CAAC,CAAC,CAAC,iBAAiB,CAAC,EACtE,aAAa,iBAAiB,KAC7B,OAAO,CAAC,WAAW,EAAE,CA0BvB,CAAA"}
+{"version":3,"file":"render-security.d.ts","sourceRoot":"","sources":["../src/render-security.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,8DAA8D,CAAA;AACnG,OAAO,KAAK,EAAE,OAAO,EAA6B,WAAW,EAAE,MAAM,OAAO,CAAA;AAG5E,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,qBAAqB,CAAA;AAsD5D;;;;GAIG;AACH,eAAO,MAAM,cAAc,GACzB,cAAc,eAAe,CAAC,UAAU,CAAC,EACzC,SAAS,WAAW,CAAC,eAAe,CAAC,YAAY,CAAC,CAAC,CAAC,iBAAiB,CAAC,EACtE,aAAa,iBAAiB,EAC9B,QAAO,OAAO,CAAC,OAAO,CAAK,KAC1B,OAAO,CAAC,WAAW,EAAE,CAsBvB,CAAA"}

package/dist/render-security.js

@@ -1,10 +1,61 @@
 import { getResolvedRef } from '@scalar/workspace-store/helpers/get-resolved-ref';
-import { heading, item, list, paragraph, strong, text } from './markdown-nodes.js';
-/** Preserve OR between requirements and AND between schemes within a requirement. */
-export const renderSecurity = async (requirements, schemes, description) => {
+import { heading, inlineCode, item, list, paragraph, strong, text } from './markdown-nodes.js';
+const flowNames = {
+    implicit: 'implicit',
+    password: 'password',
+    clientCredentials: 'client credentials',
+    authorizationCode: 'authorization code',
+    deviceAuthorization: 'device authorization',
+};
+/** Summarize a security scheme on one line, for example "API key in header `X-Api-Key`". */
+const summarizeScheme = (scheme) => {
+    const value = scheme;
+    switch (value.type) {
+        case 'apiKey':
+            return [text(`API key in ${String(value.in ?? 'header')} `), inlineCode(value.name)];
+        case 'http': {
+            const name = typeof value.scheme === 'string' ? value.scheme.toLowerCase() : '';
+            return [
+                text(`HTTP ${name || 'authentication'}`),
+                ...(typeof value.bearerFormat === 'string' ? [text(' ('), inlineCode(value.bearerFormat), text(')')] : []),
+            ];
+        }
+        case 'oauth2': {
+            const flows = Object.entries(typeof value.flows === 'object' && value.flows ? value.flows : {});
+            const nodes = [text('OAuth 2.0')];
+            for (const [index, [flow, settings]] of flows.entries()) {
+                const urls = settings;
+                nodes.push(text(`${index ? '; ' : ': '}${flowNames[flow] ?? flow}`));
+                for (const [key, label] of [
+                    ['authorizationUrl', 'authorize'],
+                    ['deviceAuthorizationUrl', 'device authorization'],
+                    ['tokenUrl', 'token'],
+                    ['refreshUrl', 'refresh'],
+                ]) {
+                    // Coercion fills in optional URLs as empty strings.
+                    if (typeof urls[key] === 'string' && urls[key])
+                        nodes.push(text(`, ${label} `), inlineCode(urls[key]));
+                }
+            }
+            return nodes;
+        }
+        case 'openIdConnect':
+            return [text('OpenID Connect '), inlineCode(value.openIdConnectUrl)];
+        case 'mutualTLS':
+            return [text('Mutual TLS')];
+        default:
+            return [inlineCode(value.type)];
+    }
+};
+/**
+ * Preserve OR between requirements and AND between schemes within a requirement.
+ * Without declared requirements there is nothing to say: only an explicit empty list means that
+ * no authentication is required.
+ */
+export const renderSecurity = async (requirements, schemes, description, level = 4) => {
     if (!requirements)
         return [];
-    const nodes = [heading(4, text('Authentication'))];
+    const nodes = [heading(level, text('Authentication'))];
     if (!requirements.length)
         nodes.push(paragraph(text('No authentication required.')));
     for (const [index, requirement] of requirements.entries()) {
@@ -17,15 +68,13 @@ export const renderSecurity = async (requirements, schemes, description) => {
         }
         const entriesNodes = [];
         for (const [name, scopes] of entries) {
-            const blocks = [
-                paragraph(strong(text(name)), ...(scopes?.length ? [text(` Scopes: ${scopes.join(', ')}`)] : [])),
-            ];
             const scheme = getResolvedRef(schemes?.[name]);
-            if (scheme) {
-                blocks.push({ type: 'code', value: JSON.stringify(scheme, null, 2) });
-                blocks.push(...(await description(scheme.description)));
-            }
-            entriesNodes.push(item(...blocks));
+            const line = [strong(text(name))];
+            if (scheme)
+                line.push(text(': '), ...summarizeScheme(scheme));
+            if (scopes?.length)
+                line.push(text(', scopes: '), inlineCode(scopes.join(', ')));
+            entriesNodes.push(item(paragraph(...line), ...(await description(scheme?.description))));
         }
         nodes.push(list(entriesNodes));
     }

package/dist/select-document.d.ts

@@ -10,9 +10,26 @@ export type OperationSelector = {
     pointer: string;
 };
 /** Select one reference page, or omit selectors for the whole document. */
-export type OpenApiRenderOptions = {
+export type OpenApiRenderOptions = SchemaReferenceOptions & ({
     [Key in keyof PageSelectors]: Partial<Record<Exclude<keyof PageSelectors, Key>, never>> & Pick<PageSelectors, Key>;
-}[keyof PageSelectors] | Partial<Record<keyof PageSelectors, never>>;
+}[keyof PageSelectors] | Partial<Record<keyof PageSelectors, never>>);
+/** Control shared-schema expansion without assuming a documentation URL layout. */
+export type SchemaReferenceOptions = {
+    /** Expand root schemas, link nested references, and omit generated examples and the transitive appendix. */
+    schemaReferences?: {
+        mode: 'linked';
+        /** Return a published URL, or undefined to retain the schema name as plain text. */
+        resolveUrl?: (reference: {
+            ref: string;
+            name: string;
+        }) => string | undefined;
+        /**
+         * Render references to primitive, enum and `const` schemas, and to aliases of them, in place
+         * instead of linking them. Their whole definition fits on one line. Defaults to `true`.
+         */
+        inlinePrimitives?: boolean;
+    };
+};
 type PageSelectors = {
     operation: OperationSelector;
     tag: string;

package/dist/select-document.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"select-document.d.ts","sourceRoot":"","sources":["../src/select-document.ts"],"names":[],"mappings":"AASA,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,4CAA4C,CAAA;AACjF,OAAO,KAAK,EAAE,eAAe,EAAkB,MAAM,8DAA8D,CAAA;AAEnH,gFAAgF;AAChF,MAAM,MAAM,iBAAiB,GACzB;IACE,IAAI,EAAE,MAAM,CAAA;IACZ,MAAM,EAAE,eAAe,CAAA;CACxB,GACD;IACE,WAAW,EAAE,MAAM,CAAA;CACpB,GACD;IACE,OAAO,EAAE,MAAM,CAAA;CAChB,CAAA;AACL,2EAA2E;AAC3E,MAAM,MAAM,oBAAoB,GAC5B;KACG,GAAG,IAAI,MAAM,aAAa,GAAG,OAAO,CAAC,MAAM,CAAC,OAAO,CAAC,MAAM,aAAa,EAAE,GAAG,CAAC,EAAE,KAAK,CAAC,CAAC,GAAG,IAAI,CAAC,aAAa,EAAE,GAAG,CAAC;CACnH,CAAC,MAAM,aAAa,CAAC,GACtB,OAAO,CAAC,MAAM,CAAC,MAAM,aAAa,EAAE,KAAK,CAAC,CAAC,CAAA;AAE/C,KAAK,aAAa,GAAG;IACnB,SAAS,EAAE,iBAAiB,CAAA;IAC5B,GAAG,EAAE,MAAM,CAAA;IACX,KAAK,EAAE,MAAM,CAAA;IACb,OAAO,EAAE;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,MAAM,EAAE,eAAe,CAAA;KAAE,CAAA;IAClD,YAAY,EAAE,IAAI,CAAA;CACnB,CAAA;AAyKD,sEAAsE;AACtE,eAAO,MAAM,cAAc,GAAI,UAAU,eAAe,EAAE,UAAS,oBAAyB,KAAG,eAuN9F,CAAA"}
+{"version":3,"file":"select-document.d.ts","sourceRoot":"","sources":["../src/select-document.ts"],"names":[],"mappings":"AASA,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,4CAA4C,CAAA;AACjF,OAAO,KAAK,EAAE,eAAe,EAAkB,MAAM,8DAA8D,CAAA;AAEnH,gFAAgF;AAChF,MAAM,MAAM,iBAAiB,GACzB;IACE,IAAI,EAAE,MAAM,CAAA;IACZ,MAAM,EAAE,eAAe,CAAA;CACxB,GACD;IACE,WAAW,EAAE,MAAM,CAAA;CACpB,GACD;IACE,OAAO,EAAE,MAAM,CAAA;CAChB,CAAA;AACL,2EAA2E;AAC3E,MAAM,MAAM,oBAAoB,GAAG,sBAAsB,GACvD,CACI;KACG,GAAG,IAAI,MAAM,aAAa,GAAG,OAAO,CAAC,MAAM,CAAC,OAAO,CAAC,MAAM,aAAa,EAAE,GAAG,CAAC,EAAE,KAAK,CAAC,CAAC,GACrF,IAAI,CAAC,aAAa,EAAE,GAAG,CAAC;CAC3B,CAAC,MAAM,aAAa,CAAC,GACtB,OAAO,CAAC,MAAM,CAAC,MAAM,aAAa,EAAE,KAAK,CAAC,CAAC,CAC9C,CAAA;AAEH,mFAAmF;AACnF,MAAM,MAAM,sBAAsB,GAAG;IACnC,4GAA4G;IAC5G,gBAAgB,CAAC,EAAE;QACjB,IAAI,EAAE,QAAQ,CAAA;QACd,oFAAoF;QACpF,UAAU,CAAC,EAAE,CAAC,SAAS,EAAE;YAAE,GAAG,EAAE,MAAM,CAAC;YAAC,IAAI,EAAE,MAAM,CAAA;SAAE,KAAK,MAAM,GAAG,SAAS,CAAA;QAC7E;;;WAGG;QACH,gBAAgB,CAAC,EAAE,OAAO,CAAA;KAC3B,CAAA;CACF,CAAA;AAED,KAAK,aAAa,GAAG;IACnB,SAAS,EAAE,iBAAiB,CAAA;IAC5B,GAAG,EAAE,MAAM,CAAA;IACX,KAAK,EAAE,MAAM,CAAA;IACb,OAAO,EAAE;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,MAAM,EAAE,eAAe,CAAA;KAAE,CAAA;IAClD,YAAY,EAAE,IAAI,CAAA;CACnB,CAAA;AAyKD,sEAAsE;AACtE,eAAO,MAAM,cAAc,GAAI,UAAU,eAAe,EAAE,UAAS,oBAAyB,KAAG,eA4N9F,CAAA"}

package/dist/select-document.js

@@ -126,7 +126,7 @@ export const selectDocument = (document, options = {}) => {
     if (!isObject(options)) {
         throw new Error('Render options must be an object');
     }
-    const keys = Object.keys(options).filter((key) => options[key] !== undefined);
+    const keys = Object.keys(options).filter((key) => key !== 'schemaReferences' && options[key] !== undefined);
     if (!keys.length) {
         return document;
     }
@@ -231,8 +231,9 @@ export const selectDocument = (document, options = {}) => {
                         parameters.set(`${parameter.in}:${parameter.name}`, ref);
                     }
                 }
-                const security = operation.security ?? document.security ?? [];
-                for (const requirement of security) {
+                // Undeclared security stays undeclared: an empty list would claim that no authentication is required.
+                const security = operation.security ?? document.security;
+                for (const requirement of security ?? []) {
                     for (const name of Object.keys(requirement)) {
                         securityNames.add(name);
                     }
@@ -320,9 +321,11 @@ export const selectDocument = (document, options = {}) => {
             }
         }
     };
-    visit({ paths: selected.paths, webhooks: selected.webhooks });
-    for (const root of modelRoots) {
-        visit(root);
+    if (options.schemaReferences?.mode !== 'linked') {
+        visit({ paths: selected.paths, webhooks: selected.webhooks });
+        for (const root of modelRoots) {
+            visit(root);
+        }
     }
     selected.components = {
         ...document.components,

package/package.json

@@ -16,7 +16,7 @@
     "llm",
     "swagger"
   ],
-  "version": "1.3.0",
+  "version": "1.5.0",
   "engines": {
     "node": ">=22"
   },
@@ -41,10 +41,10 @@
   ],
   "dependencies": {
     "@scalar/code-highlight": "0.4.7",
-    "@scalar/helpers": "0.15.0",
-    "@scalar/json-magic": "0.15.2",
-    "@scalar/openapi-upgrader": "0.4.0",
-    "@scalar/workspace-store": "0.67.0",
+    "@scalar/helpers": "0.16.0",
+    "@scalar/json-magic": "0.15.3",
+    "@scalar/openapi-upgrader": "0.4.1",
+    "@scalar/workspace-store": "0.67.2",
     "rehype-parse": "^9.0.1",
     "rehype-remark": "^10.0.1",
     "rehype-sanitize": "^6.0.0",
@@ -54,16 +54,25 @@
     "unified": "^11.0.5"
   },
   "devDependencies": {
-    "@hono/node-server": "^2.1.1",
+    "@scalar/components": "0.30.5",
     "@scalar/galaxy": "0.7.1",
+    "@scalar/themes": "0.18.1",
+    "@tailwindcss/vite": "^4.3.3",
     "@types/mdast": "^4.0.4",
-    "hono": "^4.13.8",
-    "vitest": "4.1.10"
+    "@vitejs/plugin-vue": "^6.0.8",
+    "marked": "^14.0.0",
+    "rehype-stringify": "^10.0.1",
+    "tailwindcss": "^4.3.3",
+    "tsx": "4.19.4",
+    "vite": "8.1.5",
+    "vitest": "4.1.10",
+    "vue": "^3.5.40",
+    "vue-tsc": "^3.3.8"
   },
   "scripts": {
     "build": "tsc -p tsconfig.build.json && tsc-alias -p tsconfig.build.json",
-    "dev": "tsx watch playground/index.ts",
+    "dev": "cd playground && vite",
     "test": "vitest --run",
-    "types:check": "tsgo --noEmit"
+    "types:check": "tsgo --noEmit && vue-tsc --noEmit -p playground/tsconfig.json"
   }
 }