@mintlify/common 1.0.1356 → 1.0.1357

package/dist/openapi/filenameUtils.d.ts

@@ -1,3 +1,12 @@
 import { NavigationEntry } from '@mintlify/models';
+import type { OpenApiSlugSource } from '@mintlify/validation';
 export declare const prepareStringToBeValidFilename: (str?: string) => string | undefined;
 export declare const generateUniqueFilenameWithoutExtension: (pages: NavigationEntry[] | Readonly<Record<string, unknown>>, base: string) => string;
+export type { OpenApiSlugSource };
+export declare const operationIdToSlug: (operationId?: string) => string | undefined;
+export declare const getOperationSlugBase: ({ slugSource, operationId, summary, fallback, }: {
+    slugSource: OpenApiSlugSource | undefined;
+    operationId: string | undefined;
+    summary: string | undefined;
+    fallback: () => string;
+}) => string;

package/dist/openapi/filenameUtils.js

@@ -26,3 +26,23 @@ export const generateUniqueFilenameWithoutExtension = (pages, base) => {
     }
     return filename.toLowerCase();
 };
+export const operationIdToSlug = (operationId) => {
+    if (!operationId)
+        return undefined;
+    const slug = operationId
+        .replace(/([A-Z]+)([A-Z][a-z])/g, '$1-$2')
+        .replace(/([a-z0-9])([A-Z])/g, '$1-$2')
+        .replace(/[^A-Za-z0-9]+/g, '-')
+        .replace(/^-+|-+$/g, '')
+        .toLowerCase();
+    return slug.length > 0 ? slug : undefined;
+};
+export const getOperationSlugBase = ({ slugSource, operationId, summary, fallback, }) => {
+    var _a;
+    if (slugSource === 'operationId') {
+        const fromOperationId = operationIdToSlug(operationId);
+        if (fromOperationId)
+            return fromOperationId;
+    }
+    return (_a = prepareStringToBeValidFilename(summary)) !== null && _a !== void 0 ? _a : fallback();
+};

package/dist/openapi/generateOpenApiPages.d.ts

@@ -5,6 +5,7 @@
  */
 import type { PageMetaTags } from '@mintlify/models';
 import { type DocumentV3 } from '@mintlify/validation';
+import { type OpenApiSlugSource } from './filenameUtils.js';
 import { type OpenApiTagGroup } from './tagHierarchy.js';
 /**
  * Build MDX content string matching what createOpenApiFrontmatter produces in prebuild.
@@ -50,5 +51,7 @@ export type GenerateOpenApiPagesOptions = {
     outputDirectory?: string;
     /** Optional API version string */
     version?: string;
+    /** What the last slug segment is derived from; defaults to the operation summary */
+    slug?: OpenApiSlugSource;
 };
 export declare function generateOpenApiPages(opts: GenerateOpenApiPagesOptions): GeneratedApiPage[];

package/dist/openapi/generateOpenApiPages.js

@@ -4,7 +4,7 @@ import { optionallyAddLeadingSlash } from '../fs/optionallySlash.js';
 import { mergePageGroups } from '../navigation/groupAccess.js';
 import { slugToTitle } from '../slug/slugToTitle.js';
 import { buildOpenApiMetaTag } from './buildOpenApiMetaTag.js';
-import { prepareStringToBeValidFilename, generateUniqueFilenameWithoutExtension, } from './filenameUtils.js';
+import { prepareStringToBeValidFilename, generateUniqueFilenameWithoutExtension, getOperationSlugBase, } from './filenameUtils.js';
 import { getOpenApiTitleAndDescription } from './getOpenApiTitleAndDescription.js';
 import { createOpenApiBadgeResolver, createOpenApiTagResolver, isOpenApi32, } from './tagHierarchy.js';
 /**
@@ -74,8 +74,8 @@ function getXMintGroups(pathObject, operationObject) {
 }
 export function generateOpenApiPages(opts) {
     var _a, _b, _c, _d, _e, _f, _g, _h;
-    var _j, _k, _l, _m, _o, _p, _q, _r, _s, _t, _u, _v, _w, _x, _y;
-    const { spec, specFilePath, outputDirectory } = opts;
+    var _j, _k, _l, _m, _o, _p, _q, _r, _s, _t, _u, _v, _w;
+    const { spec, specFilePath, outputDirectory, slug: slugSource } = opts;
     const outDir = outputDirectory !== null && outputDirectory !== void 0 ? outputDirectory : DEFAULT_OUTPUT_DIR;
     const openApiFilePathFromRoot = optionallyAddLeadingSlash(specFilePath);
     const pages = [];
@@ -108,8 +108,13 @@ export function generateOpenApiPages(opts) {
             const tagPath = resolveTags(operation.tags);
             const tagName = (_a = tagPath.at(-1)) === null || _a === void 0 ? void 0 : _a.name;
             const groupName = (_b = tagPath.at(-1)) === null || _b === void 0 ? void 0 : _b.label;
-            let title = (_m = prepareStringToBeValidFilename(operation.summary)) !== null && _m !== void 0 ? _m : `${method.toLowerCase()}-${prepareStringToBeValidFilename(apiPath)}`;
-            let folder = (_o = prepareStringToBeValidFilename(tagName)) !== null && _o !== void 0 ? _o : '';
+            let title = getOperationSlugBase({
+                slugSource,
+                operationId: operation.operationId,
+                summary: operation.summary,
+                fallback: () => `${method.toLowerCase()}-${prepareStringToBeValidFilename(apiPath)}`,
+            });
+            let folder = (_m = prepareStringToBeValidFilename(tagName)) !== null && _m !== void 0 ? _m : '';
             let base = posixJoin(outDir, folder, title);
             if (xMint === null || xMint === void 0 ? void 0 : xMint.href) {
                 const href = xMint.href.startsWith('/') ? xMint.href.slice(1) : xMint.href;
@@ -134,7 +139,7 @@ export function generateOpenApiPages(opts) {
             if (badge !== undefined && (xMintMetadata === null || xMintMetadata === void 0 ? void 0 : xMintMetadata.tag) === undefined) {
                 xMintMetadata = Object.assign(Object.assign({}, xMintMetadata), { tag: badge });
             }
-            const page = Object.assign(Object.assign({ title: (_q = (_p = xMintMetadata === null || xMintMetadata === void 0 ? void 0 : xMintMetadata.title) !== null && _p !== void 0 ? _p : titleTag) !== null && _q !== void 0 ? _q : slugToTitle(filenameWithoutExtension), description: (_r = xMintMetadata === null || xMintMetadata === void 0 ? void 0 : xMintMetadata.description) !== null && _r !== void 0 ? _r : description, deprecated: (_s = xMintMetadata === null || xMintMetadata === void 0 ? void 0 : xMintMetadata.deprecated) !== null && _s !== void 0 ? _s : operation.deprecated, openapi: openapiMetaTag, href: posixResolve('/', filenameWithoutExtension), method, path: apiPath, tag: groupName }, (nestedTags ? { tagPath } : {})), { hidden: operation['x-hidden'] === true, xMintMetadata, xMintContent: xMint === null || xMint === void 0 ? void 0 : xMint.content, version: opts.version });
+            const page = Object.assign(Object.assign({ title: (_p = (_o = xMintMetadata === null || xMintMetadata === void 0 ? void 0 : xMintMetadata.title) !== null && _o !== void 0 ? _o : titleTag) !== null && _p !== void 0 ? _p : slugToTitle(filenameWithoutExtension), description: (_q = xMintMetadata === null || xMintMetadata === void 0 ? void 0 : xMintMetadata.description) !== null && _q !== void 0 ? _q : description, deprecated: (_r = xMintMetadata === null || xMintMetadata === void 0 ? void 0 : xMintMetadata.deprecated) !== null && _r !== void 0 ? _r : operation.deprecated, openapi: openapiMetaTag, href: posixResolve('/', filenameWithoutExtension), method, path: apiPath, tag: groupName }, (nestedTags ? { tagPath } : {})), { hidden: operation['x-hidden'] === true, xMintMetadata, xMintContent: xMint === null || xMint === void 0 ? void 0 : xMint.content, version: opts.version });
             pages.push(page);
         }
     }
@@ -148,7 +153,7 @@ export function generateOpenApiPages(opts) {
             if (!webhookObject || typeof webhookObject !== 'object')
                 continue;
             // eslint-disable-next-line @typescript-eslint/consistent-type-assertions
-            const pathItem = ((_t = resolvePathItemReference(webhookObject, spec.components)) !== null && _t !== void 0 ? _t : webhookObject);
+            const pathItem = ((_s = resolvePathItemReference(webhookObject, spec.components)) !== null && _s !== void 0 ? _s : webhookObject);
             for (const [, pathOperation] of getPathItemOperations(pathItem)) {
                 // eslint-disable-next-line @typescript-eslint/consistent-type-assertions
                 const operation = pathOperation;
@@ -158,8 +163,14 @@ export function generateOpenApiPages(opts) {
                 const tagPath = resolveTags(operation.tags);
                 const tagName = (_c = tagPath.at(-1)) === null || _c === void 0 ? void 0 : _c.name;
                 const groupName = (_d = tagPath.at(-1)) === null || _d === void 0 ? void 0 : _d.label;
-                let title = (_u = prepareStringToBeValidFilename(operation.summary)) !== null && _u !== void 0 ? _u : `${prepareStringToBeValidFilename(webhook)}`;
-                let folder = (_v = prepareStringToBeValidFilename(tagName)) !== null && _v !== void 0 ? _v : '';
+                const summaryTitle = prepareStringToBeValidFilename(operation.summary);
+                let title = getOperationSlugBase({
+                    slugSource,
+                    operationId: operation.operationId,
+                    summary: operation.summary,
+                    fallback: () => `${prepareStringToBeValidFilename(webhook)}`,
+                });
+                let folder = (_t = prepareStringToBeValidFilename(tagName)) !== null && _t !== void 0 ? _t : '';
                 let base = posixJoin(outDir, folder, title);
                 if (xMint === null || xMint === void 0 ? void 0 : xMint.href) {
                     const href = xMint.href.startsWith('/') ? xMint.href.slice(1) : xMint.href;
@@ -178,7 +189,7 @@ export function generateOpenApiPages(opts) {
                 const badge = resolveBadge(operation.tags);
                 const xMintMetadata = badge !== undefined && ((_e = xMint === null || xMint === void 0 ? void 0 : xMint.metadata) === null || _e === void 0 ? void 0 : _e.tag) === undefined
                     ? Object.assign(Object.assign({}, xMint === null || xMint === void 0 ? void 0 : xMint.metadata), { tag: badge }) : xMint === null || xMint === void 0 ? void 0 : xMint.metadata;
-                const page = Object.assign(Object.assign({ title: (_w = (_f = xMint === null || xMint === void 0 ? void 0 : xMint.metadata) === null || _f === void 0 ? void 0 : _f.title) !== null && _w !== void 0 ? _w : slugToTitle(filenameWithoutExtension), description: (_x = (_g = xMint === null || xMint === void 0 ? void 0 : xMint.metadata) === null || _g === void 0 ? void 0 : _g.description) !== null && _x !== void 0 ? _x : operation.description, deprecated: (_y = (_h = xMint === null || xMint === void 0 ? void 0 : xMint.metadata) === null || _h === void 0 ? void 0 : _h.deprecated) !== null && _y !== void 0 ? _y : operation.deprecated, openapi: openapiMetaTag, href: posixResolve('/', filenameWithoutExtension), method: 'webhook', path: webhook, tag: groupName }, (nestedTags ? { tagPath } : {})), { hidden: operation['x-hidden'] === true, isWebhook: true, xMintMetadata, xMintContent: xMint === null || xMint === void 0 ? void 0 : xMint.content, version: opts.version });
+                const page = Object.assign(Object.assign({ title: (_u = (_f = xMint === null || xMint === void 0 ? void 0 : xMint.metadata) === null || _f === void 0 ? void 0 : _f.title) !== null && _u !== void 0 ? _u : slugToTitle(slugSource === 'operationId' && summaryTitle ? summaryTitle : filenameWithoutExtension), description: (_v = (_g = xMint === null || xMint === void 0 ? void 0 : xMint.metadata) === null || _g === void 0 ? void 0 : _g.description) !== null && _v !== void 0 ? _v : operation.description, deprecated: (_w = (_h = xMint === null || xMint === void 0 ? void 0 : xMint.metadata) === null || _h === void 0 ? void 0 : _h.deprecated) !== null && _w !== void 0 ? _w : operation.deprecated, openapi: openapiMetaTag, href: posixResolve('/', filenameWithoutExtension), method: 'webhook', path: webhook, tag: groupName }, (nestedTags ? { tagPath } : {})), { hidden: operation['x-hidden'] === true, isWebhook: true, xMintMetadata, xMintContent: xMint === null || xMint === void 0 ? void 0 : xMint.content, version: opts.version });
                 pages.push(page);
             }
         }

package/dist/openapi/index.d.ts

@@ -14,7 +14,7 @@ export { getMatchingOpenApiFile, type ApiReferenceMapping, type FileToUuidMap, t
 export { parseApiString } from './parseApiString.js';
 export { findOpenApiPath } from './findOpenApiPath.js';
 export { openApiMetaTagToEndpointRef } from './endpointRef.js';
-export { prepareStringToBeValidFilename, generateUniqueFilenameWithoutExtension, } from './filenameUtils.js';
+export { prepareStringToBeValidFilename, generateUniqueFilenameWithoutExtension, getOperationSlugBase, operationIdToSlug, type OpenApiSlugSource, } from './filenameUtils.js';
 export { findNavGroup, DEFAULT_API_GROUP_NAME, DEFAULT_WEBSOCKETS_GROUP_NAME, } from './findNavGroup.js';
 export { generateOpenApiPages, buildGeneratedMdxContent, type GeneratedApiPage, type GenerateOpenApiPagesOptions, } from './generateOpenApiPages.js';
 export { getTagDisplayName } from './getTagDisplayName.js';

package/dist/openapi/index.js

@@ -14,7 +14,7 @@ export { getMatchingOpenApiFile, } from './getMatchingOpenApiFile.js';
 export { parseApiString } from './parseApiString.js';
 export { findOpenApiPath } from './findOpenApiPath.js';
 export { openApiMetaTagToEndpointRef } from './endpointRef.js';
-export { prepareStringToBeValidFilename, generateUniqueFilenameWithoutExtension, } from './filenameUtils.js';
+export { prepareStringToBeValidFilename, generateUniqueFilenameWithoutExtension, getOperationSlugBase, operationIdToSlug, } from './filenameUtils.js';
 export { findNavGroup, DEFAULT_API_GROUP_NAME, DEFAULT_WEBSOCKETS_GROUP_NAME, } from './findNavGroup.js';
 export { generateOpenApiPages, buildGeneratedMdxContent, } from './generateOpenApiPages.js';
 export { getTagDisplayName } from './getTagDisplayName.js';