@mintlify/scraping 4.0.1072 → 4.0.1073

package/__test__/openApiTagHierarchy.test.ts

@@ -0,0 +1,286 @@
+import { generateOpenApiPages as generateEditorPages } from '@mintlify/common';
+import type { OpenAPIV3_2 } from '@mintlify/validation';
+import type { OpenAPI } from 'openapi-types';
+import { describe, expect, it } from 'vitest';
+
+import { generateOpenApiPages } from '../src/openapi/generateOpenApiPages.js';
+import { generateOpenApiPagesForDocsConfig } from '../src/openapi/generateOpenApiPagesForDocsConfig.js';
+
+const endpoint = (tags: string[], summary: string) => ({
+  get: { tags, summary, responses: { '200': { description: 'OK' } } },
+});
+
+type Tag = { name: string; parent?: string; summary?: string; kind?: string };
+
+function document() {
+  const tags: Tag[] = [
+    { name: 'books', parent: 'products', summary: 'Books' },
+    { name: 'products', parent: 'store', summary: 'Products' },
+    { name: 'store', summary: 'Store' },
+  ];
+  return {
+    openapi: '3.2.0',
+    info: { title: 'Store', version: '1' },
+    tags,
+    paths: {
+      '/books': endpoint(['books'], 'List books'),
+      '/products': endpoint(['products'], 'List products'),
+    },
+    webhooks: {
+      bookCreated: {
+        post: {
+          tags: ['books'],
+          summary: 'Book created',
+          responses: { '200': { description: 'OK' } },
+        },
+      },
+    },
+  };
+}
+
+describe('3.2 methods', () => {
+  it('generates pages for query and additionalOperations with the wire method in the meta tag', async () => {
+    const base = document();
+    const spec: OpenAPIV3_2.Document = {
+      ...base,
+      paths: {
+        ...base.paths,
+        '/books': {
+          ...base.paths['/books'],
+          query: {
+            tags: ['books'],
+            summary: 'Search books',
+            responses: { '200': { description: 'OK' } },
+          },
+          additionalOperations: {
+            PURGE: {
+              tags: ['books'],
+              summary: 'Purge books',
+              responses: { '204': { description: 'Purged' } },
+            },
+          },
+        },
+      },
+    };
+    const { pagesAcc } = await generateOpenApiPagesForDocsConfig(spec as OpenAPI.Document, {
+      writeFiles: false,
+      outDir: 'api-reference',
+    });
+    expect(Object.values(pagesAcc).map((page) => [page.href, page.openapi])).toEqual(
+      expect.arrayContaining([
+        ['/api-reference/books/search-books', 'query /books'],
+        ['/api-reference/books/purge-books', 'PURGE /books'],
+      ])
+    );
+  });
+});
+
+describe.each([
+  ['docs.json', generateOpenApiPagesForDocsConfig],
+  ['mint.json', generateOpenApiPages],
+] as const)('%s tag hierarchy', (_name, generate) => {
+  it('generates nested paths and webhooks with matching decorated navigation and stable URLs', async () => {
+    const spec = document();
+    const result = await generate(spec, {
+      writeFiles: false,
+      outDir: 'api-reference',
+    });
+    expect(result.nav).toEqual([
+      {
+        group: 'Store',
+        pages: [
+          {
+            group: 'Products',
+            pages: [
+              {
+                group: 'Books',
+                pages: ['api-reference/books/list-books', 'api-reference/books/book-created'],
+              },
+              'api-reference/products/list-products',
+            ],
+          },
+        ],
+      },
+    ]);
+    expect(result.decoratedNav).toMatchObject([
+      {
+        group: 'Store',
+        pages: [
+          {
+            group: 'Products',
+            pages: [
+              {
+                group: 'Books',
+                pages: [
+                  { href: '/api-reference/books/list-books' },
+                  { href: '/api-reference/books/book-created' },
+                ],
+              },
+              { href: '/api-reference/products/list-products' },
+            ],
+          },
+        ],
+      },
+    ]);
+    const flat = await generate(
+      { ...spec, tags: spec.tags.map(({ name }) => ({ name })), openapi: '3.1.0' },
+      { writeFiles: false, outDir: 'api-reference' }
+    );
+    expect(Object.keys(result.pagesAcc)).toEqual(Object.keys(flat.pagesAcc));
+    expect(
+      generateEditorPages({ spec, specFilePath: 'openapi.yaml' })
+        .map((page) => page.href)
+        .sort()
+    ).toEqual(
+      Object.values(result.pagesAcc)
+        .map((page) => page.href)
+        .sort()
+    );
+  });
+
+  it('does not merge distinct tags with identical labels', async () => {
+    const spec = {
+      ...document(),
+      webhooks: {},
+      tags: [
+        { name: 'books', parent: 'store', summary: 'Items' },
+        { name: 'products', parent: 'store', summary: 'Items' },
+        { name: 'store' },
+      ],
+    };
+    const { nav } = await generate(spec, { writeFiles: false });
+    expect(nav).toEqual([
+      {
+        group: 'store',
+        pages: [
+          { group: 'Items', pages: ['books/list-books'] },
+          { group: 'Items', pages: ['products/list-products'] },
+        ],
+      },
+    ]);
+  });
+
+  it('keeps filenames unique when different tag names produce the same slug', async () => {
+    const spec = {
+      ...document(),
+      webhooks: {},
+      tags: [{ name: 'book.s' }, { name: 'books' }],
+      paths: {
+        '/first': endpoint(['book.s'], 'List'),
+        '/second': endpoint(['books'], 'List'),
+      },
+    };
+    const { pagesAcc } = await generate(spec, {
+      writeFiles: false,
+      outDir: 'api-reference',
+    });
+    expect(Object.keys(pagesAcc)).toEqual([
+      'api-reference/books/list',
+      'api-reference/books/list-1',
+    ]);
+    expect(
+      generateEditorPages({ spec, specFilePath: 'openapi.yaml' }).map((page) => page.href)
+    ).toEqual(['/api-reference/books/list', '/api-reference/books/list-1']);
+  });
+
+  it('omits groups containing only hidden or excluded operations', async () => {
+    const spec = document();
+    const hiddenSpec = {
+      ...spec,
+      webhooks: {},
+      paths: {
+        '/books': { get: { ...spec.paths['/books'].get, 'x-hidden': true } },
+        '/products': { get: { ...spec.paths['/products'].get, 'x-excluded': true } },
+      },
+    };
+    const { nav, pagesAcc } = await generate(hiddenSpec, {
+      writeFiles: false,
+    });
+    expect(nav).toEqual([]);
+    expect(Object.keys(pagesAcc)).toEqual(['books/list-books']);
+  });
+
+  it('supports webhook-only specs and rejects specs with no operations', async () => {
+    const { paths: _paths, ...spec } = document();
+    const result = await generate(spec, { writeFiles: false });
+    expect(Object.keys(result.pagesAcc)).toEqual(['books/book-created']);
+    await expect(generate({ ...spec, webhooks: {} }, { writeFiles: false })).rejects.toThrow(
+      'No paths or webhooks'
+    );
+  });
+
+  it('turns kind: badge tags into the page tag pill without grouping by them', async () => {
+    const spec = document();
+    spec.tags.push(
+      { name: 'beta', kind: 'badge', summary: 'Beta' },
+      { name: 'internal', kind: 'badge', summary: 'Internal: staff only' }
+    );
+    spec.paths['/books'].get.tags = ['books', 'beta'];
+    spec.paths['/products'].get.tags = ['products', 'internal', 'beta'];
+    spec.webhooks.bookCreated.post.tags = ['books', 'beta'];
+    const written: Record<string, string> = {};
+    const result = await generate(spec, {
+      writeFiles: true,
+      writeFile: (path, contents) => {
+        written[path] = contents;
+      },
+      outDir: 'api-reference',
+    });
+    expect(result.pagesAcc['api-reference/books/list-books']?.tag).toBe('Beta');
+    expect(result.pagesAcc['api-reference/products/list-products']?.tag).toBe(
+      'Internal: staff only'
+    );
+    expect(result.pagesAcc['api-reference/books/book-created']?.tag).toBe('Beta');
+    expect(written['api-reference/books/list-books.mdx']).toContain('\ntag: Beta\n');
+    expect(written['api-reference/products/list-products.mdx']).toContain(
+      "\ntag: 'Internal: staff only'\n"
+    );
+    expect(result.nav[0]).toMatchObject({ group: 'Store' });
+    expect(JSON.stringify(result.nav)).not.toContain('Beta');
+
+    const editorPages = generateEditorPages({
+      spec,
+      specFilePath: 'openapi.yaml',
+      outputDirectory: 'api-reference',
+    });
+    expect(editorPages.map((page) => page.xMintMetadata?.tag)).toEqual([
+      'Beta',
+      'Internal: staff only',
+      'Beta',
+    ]);
+  });
+
+  it('files a page under its navigation tag when a badge tag is listed first', async () => {
+    const spec = document();
+    spec.tags.push({ name: 'beta', kind: 'badge', summary: 'Beta' });
+    spec.paths['/books'].get.tags = ['beta', 'books'];
+    spec.webhooks.bookCreated.post.tags = ['beta', 'books'];
+    const result = await generate(spec, { writeFiles: false, outDir: 'api-reference' });
+    expect(Object.keys(result.pagesAcc)).toEqual(
+      expect.arrayContaining(['api-reference/books/list-books', 'api-reference/books/book-created'])
+    );
+
+    const editorPages = generateEditorPages({
+      spec,
+      specFilePath: 'openapi.yaml',
+      outputDirectory: 'api-reference',
+    });
+    expect(editorPages.map((page) => page.href)).toEqual(
+      expect.arrayContaining([
+        '/api-reference/books/list-books',
+        '/api-reference/books/book-created',
+      ])
+    );
+  });
+
+  it('lets x-mint metadata tag override a badge tag', async () => {
+    const spec = document();
+    spec.tags.push({ name: 'beta', kind: 'badge' });
+    Object.assign(spec.paths['/books'].get, {
+      tags: ['books', 'beta'],
+      'x-mint': { metadata: { tag: 'PREVIEW' } },
+    });
+    const result = await generate(spec, { writeFiles: false });
+    expect(result.pagesAcc['books/list-books']?.tag).toBe('PREVIEW');
+  });
+});

package/bin/openapi/common.d.ts

@@ -1,4 +1,4 @@
-import { type LoadedOverlay } from '@mintlify/common';
+import { createOpenApiBadgeResolver, createOpenApiTagResolver, type LoadedOverlay } from '@mintlify/common';
 import type { DecoratedNavigationPage, PageMetaTags } from '@mintlify/models';
 import { XMint } from '@mintlify/validation';
 import { OpenAPI, OpenAPIV3 } from 'openapi-types';
@@ -35,6 +35,8 @@ export type GenerateOpenApiPagesOptions = {
     mountPath?: string;
     overwrite?: boolean;
     localSchema?: boolean;
+    resolveTags?: ReturnType<typeof createOpenApiTagResolver>;
+    resolveBadge?: ReturnType<typeof createOpenApiBadgeResolver>;
     writeFile?: (filename: string, content: string) => void | Promise<void>;
     overlays?: readonly LoadedOverlay[];
 };
@@ -45,8 +47,8 @@ export type OpenApiPageGenerationResult<N, DN> = {
     pagesAcc: Record<string, DecoratedNavigationPage>;
     isUrl: boolean;
 };
-export declare function processOpenApiPath<N, DN>(path: string, pathItemObject: OpenAPIV3.PathItemObject<OpenApiExtensions>, schema: OpenAPI.Document, nav: N, decoratedNav: DN, writePromises: Promise<void>[], pagesAcc: Record<string, DecoratedNavigationPage>, options: GenerateOpenApiPagesOptions, findNavGroup: (nav: any, groupName?: string) => any): string[];
-export declare function processOpenApiWebhook<N, DN>(webhook: string, webhookObject: OpenAPIV3.PathItemObject<OpenApiExtensions>, schema: OpenAPI.Document, nav: N, decoratedNav: DN, writePromises: Promise<void>[], pagesAcc: Record<string, DecoratedNavigationPage>, options: GenerateOpenApiPagesOptions, findNavGroup: (nav: any, groupName?: string) => any): string[];
+export declare function processOpenApiPath<N, DN>(path: string, pathItemObject: OpenAPIV3.PathItemObject<OpenApiExtensions>, schema: OpenAPI.Document, nav: N, decoratedNav: DN, writePromises: Promise<void>[], pagesAcc: Record<string, DecoratedNavigationPage>, options: GenerateOpenApiPagesOptions, findNavGroup: (nav: any, groupName?: string, tagKey?: string) => any): string[];
+export declare function processOpenApiWebhook<N, DN>(webhook: string, webhookObject: OpenAPIV3.PathItemObject<OpenApiExtensions>, schema: OpenAPI.Document, nav: N, decoratedNav: DN, writePromises: Promise<void>[], pagesAcc: Record<string, DecoratedNavigationPage>, options: GenerateOpenApiPagesOptions, findNavGroup: (nav: any, groupName?: string, tagKey?: string) => any): string[];
 export declare const getXMintGroups: ({ pathObject, operationObject, }: {
     pathObject: OpenAPIV3.PathItemObject<OpenApiExtensions>;
     operationObject: OpenAPIV3.OperationObject<OpenApiExtensions> | undefined;

package/bin/openapi/common.js

@@ -1,9 +1,9 @@
-import { applyOverlays, getOpenApiTitleAndDescription, optionallyAddLeadingSlash, optionallyRemoveLeadingSlash, slugToTitle, isAllowedLocalSchemaUrl, buildOpenApiMetaTag, registerXMintContent, prepareStringToBeValidFilename, generateUniqueFilenameWithoutExtension, getTagDisplayName, mergePageGroups, } from '@mintlify/common';
+import { applyOverlays, getOpenApiTitleAndDescription, optionallyAddLeadingSlash, optionallyRemoveLeadingSlash, slugToTitle, isAllowedLocalSchemaUrl, buildOpenApiMetaTag, registerXMintContent, prepareStringToBeValidFilename, generateUniqueFilenameWithoutExtension, createOpenApiBadgeResolver, createOpenApiTagResolver, findOpenApiNavGroup, isOpenApi32, mergePageGroups, } from '@mintlify/common';
+import { getPathItemOperations } from '@mintlify/validation';
 import { outputFile } from 'fs-extra';
 import fse from 'fs-extra';
 import fs from 'fs/promises';
 import yaml from 'js-yaml';
-import { OpenAPIV3 } from 'openapi-types';
 import path, { join, parse, posix } from 'path';
 import { fetchOpenApi } from '../utils/network.js';
 export const getOpenApiDefinition = async (pathOrDocumentOrUrl, localSchema, overlays) => {
@@ -59,7 +59,8 @@ export const createOpenApiFrontmatterContent = ({ openApiMetaTag, version, depre
         Object.entries(metadata)
             .filter(([k]) => !reserved.has(k))
             .forEach(([key, value]) => {
-            frontmatter += `\n${key}: ${value}`;
+            const serialized = typeof value === 'string' ? yaml.dump(value, { lineWidth: -1 }).trimEnd() : value;
+            frontmatter += `\n${key}: ${serialized}`;
         });
     }
     frontmatter += `\n---`;
@@ -81,94 +82,99 @@ findNavGroup) {
         ? optionallyAddLeadingSlash(options.openApiFilePath)
         : undefined;
     const generatedSlugs = [];
-    Object.values(OpenAPIV3.HttpMethods).forEach((method) => {
-        if (method in pathItemObject) {
-            const operation = pathItemObject[method];
-            if (isExcludedOperation(operation)) {
-                return;
-            }
-            const xMint = operation?.['x-mint'];
-            const xMintGroups = getXMintGroups({
-                pathObject: pathItemObject,
-                operationObject: operation,
-            });
-            if (xMint?.href) {
-                xMint.href = optionallyAddLeadingSlash(xMint.href);
-            }
-            const tagName = operation?.tags?.[0];
-            const groupName = getTagDisplayName(tagName, schema);
-            let title = prepareStringToBeValidFilename(operation?.summary) ??
-                `${method}-${prepareStringToBeValidFilename(path)}`;
-            let folder = prepareStringToBeValidFilename(tagName) ?? '';
-            let base = posix.join(options.outDir ?? '', folder, title);
-            if (xMint?.href) {
-                const slug = optionallyRemoveLeadingSlash(xMint.href);
-                title = posix.parse(slug).name;
-                folder = posix.parse(slug).dir;
-                base = posix.join(options.mountPath ?? '', folder, title);
-            }
-            const navGroup = findNavGroup(nav, groupName);
-            const decoratedNavGroup = findNavGroup(decoratedNav, groupName);
-            const filenameWithoutExtension = generateUniqueFilenameWithoutExtension(navGroup, base);
-            const openapiMetaTag = buildOpenApiMetaTag({
-                filePath: openApiFilePathFromRoot,
-                method,
-                path,
-            });
-            const { title: titleTag, description } = getOpenApiTitleAndDescription([
-                {
-                    filename: options.openApiFilePath
-                        ? parse(options.openApiFilePath).name
-                        : 'filler-filename',
-                    spec: schema,
-                    originalFileLocation: openApiFilePathFromRoot,
-                },
-            ], openapiMetaTag);
-            let xMintMetadata = xMint?.metadata;
-            if (xMintGroups.length > 0) {
-                xMintMetadata = {
-                    ...xMintMetadata,
-                    groups: mergePageGroups(xMintMetadata?.groups, xMintGroups),
-                };
-            }
-            const slugTitle = slugToTitle(filenameWithoutExtension);
-            const page = {
-                title: titleTag ?? slugTitle,
-                description,
-                deprecated: operation?.deprecated,
-                version: options.version,
-                // When a file-path spec has x-mint.href overriding the path, use the slug-derived
-                // title for the sidebar so the nav shows the user-chosen name rather than the
-                // OpenAPI summary. Only for openApiFilePath specs to avoid changing URL-based behavior.
-                ...(xMint?.href && titleTag && options.openApiFilePath ? { sidebarTitle: slugTitle } : {}),
+    const resolveTags = options.resolveTags ?? createOpenApiTagResolver(schema);
+    const resolveBadge = options.resolveBadge ?? createOpenApiBadgeResolver(schema);
+    const nestedTags = isOpenApi32(schema);
+    getPathItemOperations(pathItemObject).forEach(([method, operation]) => {
+        if (isExcludedOperation(operation)) {
+            return;
+        }
+        const xMint = operation?.['x-mint'];
+        const xMintGroups = getXMintGroups({
+            pathObject: pathItemObject,
+            operationObject: operation,
+        });
+        if (xMint?.href) {
+            xMint.href = optionallyAddLeadingSlash(xMint.href);
+        }
+        const tagPath = resolveTags(operation?.tags);
+        const tagName = tagPath.at(-1)?.name;
+        let title = prepareStringToBeValidFilename(operation?.summary) ??
+            `${method.toLowerCase()}-${prepareStringToBeValidFilename(path)}`;
+        let folder = prepareStringToBeValidFilename(tagName) ?? '';
+        let base = posix.join(options.outDir ?? '', folder, title);
+        if (xMint?.href) {
+            const slug = optionallyRemoveLeadingSlash(xMint.href);
+            title = posix.parse(slug).name;
+            folder = posix.parse(slug).dir;
+            base = posix.join(options.mountPath ?? '', folder, title);
+        }
+        const hidden = isHiddenOperation(operation);
+        const navGroup = hidden && nestedTags ? [] : findOpenApiNavGroup(nav, tagPath, findNavGroup);
+        const decoratedNavGroup = hidden && nestedTags ? [] : findOpenApiNavGroup(decoratedNav, tagPath, findNavGroup);
+        const filenameWithoutExtension = generateUniqueFilenameWithoutExtension(nestedTags ? pagesAcc : navGroup, base);
+        const openapiMetaTag = buildOpenApiMetaTag({
+            filePath: openApiFilePathFromRoot,
+            method,
+            path,
+        });
+        const { title: titleTag, description } = getOpenApiTitleAndDescription([
+            {
+                filename: options.openApiFilePath
+                    ? parse(options.openApiFilePath).name
+                    : 'filler-filename',
+                spec: schema,
+                originalFileLocation: openApiFilePathFromRoot,
+            },
+        ], openapiMetaTag);
+        let xMintMetadata = xMint?.metadata;
+        if (xMintGroups.length > 0) {
+            xMintMetadata = {
                 ...xMintMetadata,
-                openapi: openapiMetaTag,
-                href: posix.resolve('/', filenameWithoutExtension),
+                groups: mergePageGroups(xMintMetadata?.groups, xMintGroups),
             };
-            if (!isHiddenOperation(operation)) {
-                navGroup.push(filenameWithoutExtension);
-                decoratedNavGroup.push(page);
-            }
-            pagesAcc[filenameWithoutExtension] = page;
-            generatedSlugs.push(filenameWithoutExtension);
-            if (!options.writeFiles) {
-                registerXMintContent(filenameWithoutExtension, xMint?.content);
-            }
-            const targetPath = options.outDirBasePath
-                ? join(options.outDirBasePath, `${filenameWithoutExtension}.mdx`)
-                : `${filenameWithoutExtension}.mdx`;
-            if (options.writeFiles && (!fse.pathExistsSync(targetPath) || options.overwrite)) {
-                const input = {
-                    openApiMetaTag: openapiMetaTag,
-                    version: options.version,
-                    deprecated: operation?.deprecated,
-                    metadata: xMintMetadata,
-                    extraContent: xMint?.content,
-                };
-                writePromises.push(options.writeFile
-                    ? Promise.resolve(options.writeFile(targetPath, createOpenApiFrontmatterContent(input)))
-                    : createOpenApiFrontmatter({ filename: targetPath, ...input }));
-            }
+        }
+        const badge = resolveBadge(operation?.tags);
+        if (badge !== undefined && xMintMetadata?.tag === undefined) {
+            xMintMetadata = { ...xMintMetadata, tag: badge };
+        }
+        const slugTitle = slugToTitle(filenameWithoutExtension);
+        const page = {
+            title: titleTag ?? slugTitle,
+            description,
+            deprecated: operation?.deprecated,
+            version: options.version,
+            // When a file-path spec has x-mint.href overriding the path, use the slug-derived
+            // title for the sidebar so the nav shows the user-chosen name rather than the
+            // OpenAPI summary. Only for openApiFilePath specs to avoid changing URL-based behavior.
+            ...(xMint?.href && titleTag && options.openApiFilePath ? { sidebarTitle: slugTitle } : {}),
+            ...xMintMetadata,
+            openapi: openapiMetaTag,
+            href: posix.resolve('/', filenameWithoutExtension),
+        };
+        if (!isHiddenOperation(operation)) {
+            navGroup.push(filenameWithoutExtension);
+            decoratedNavGroup.push(page);
+        }
+        pagesAcc[filenameWithoutExtension] = page;
+        generatedSlugs.push(filenameWithoutExtension);
+        if (!options.writeFiles) {
+            registerXMintContent(filenameWithoutExtension, xMint?.content);
+        }
+        const targetPath = options.outDirBasePath
+            ? join(options.outDirBasePath, `${filenameWithoutExtension}.mdx`)
+            : `${filenameWithoutExtension}.mdx`;
+        if (options.writeFiles && (!fse.pathExistsSync(targetPath) || options.overwrite)) {
+            const input = {
+                openApiMetaTag: openapiMetaTag,
+                version: options.version,
+                deprecated: operation?.deprecated,
+                metadata: xMintMetadata,
+                extraContent: xMint?.content,
+            };
+            writePromises.push(options.writeFile
+                ? Promise.resolve(options.writeFile(targetPath, createOpenApiFrontmatterContent(input)))
+                : createOpenApiFrontmatter({ filename: targetPath, ...input }));
         }
     });
     return generatedSlugs;
@@ -180,69 +186,74 @@ findNavGroup) {
         ? optionallyAddLeadingSlash(options.openApiFilePath)
         : undefined;
     const generatedSlugs = [];
-    Object.values(OpenAPIV3.HttpMethods).forEach((method) => {
-        if (method in webhookObject) {
-            const operation = webhookObject[method];
-            if (isExcludedOperation(operation)) {
-                return;
-            }
-            const xMint = operation?.['x-mint'];
-            if (xMint?.href) {
-                xMint.href = optionallyAddLeadingSlash(xMint.href);
-            }
-            const tagName = operation?.tags?.[0];
-            const groupName = getTagDisplayName(tagName, schema);
-            let title = prepareStringToBeValidFilename(operation?.summary) ??
-                `${prepareStringToBeValidFilename(webhook)}`;
-            let folder = prepareStringToBeValidFilename(tagName) ?? '';
-            let base = posix.join(options.outDir ?? '', folder, title);
-            if (xMint?.href) {
-                const slug = optionallyRemoveLeadingSlash(xMint.href);
-                title = posix.parse(slug).name;
-                folder = posix.parse(slug).dir;
-                base = posix.join(options.mountPath ?? '', folder, title);
-            }
-            const navGroup = findNavGroup(nav, groupName);
-            const decoratedNavGroup = findNavGroup(decoratedNav, groupName);
-            const filenameWithoutExtension = generateUniqueFilenameWithoutExtension(navGroup, base);
-            const openapiMetaTag = buildOpenApiMetaTag({
-                filePath: openApiFilePathFromRoot,
-                method: 'webhook',
-                path: webhook,
-            });
-            const page = {
-                title: slugToTitle(filenameWithoutExtension),
-                description: operation?.description,
+    const resolveTags = options.resolveTags ?? createOpenApiTagResolver(schema);
+    const resolveBadge = options.resolveBadge ?? createOpenApiBadgeResolver(schema);
+    const nestedTags = isOpenApi32(schema);
+    getPathItemOperations(webhookObject).forEach(([, operation]) => {
+        if (isExcludedOperation(operation)) {
+            return;
+        }
+        const xMint = operation?.['x-mint'];
+        if (xMint?.href) {
+            xMint.href = optionallyAddLeadingSlash(xMint.href);
+        }
+        const tagPath = resolveTags(operation?.tags);
+        const tagName = tagPath.at(-1)?.name;
+        let title = prepareStringToBeValidFilename(operation?.summary) ??
+            `${prepareStringToBeValidFilename(webhook)}`;
+        let folder = prepareStringToBeValidFilename(tagName) ?? '';
+        let base = posix.join(options.outDir ?? '', folder, title);
+        if (xMint?.href) {
+            const slug = optionallyRemoveLeadingSlash(xMint.href);
+            title = posix.parse(slug).name;
+            folder = posix.parse(slug).dir;
+            base = posix.join(options.mountPath ?? '', folder, title);
+        }
+        const hidden = isHiddenOperation(operation);
+        const navGroup = hidden && nestedTags ? [] : findOpenApiNavGroup(nav, tagPath, findNavGroup);
+        const decoratedNavGroup = hidden && nestedTags ? [] : findOpenApiNavGroup(decoratedNav, tagPath, findNavGroup);
+        const filenameWithoutExtension = generateUniqueFilenameWithoutExtension(nestedTags ? pagesAcc : navGroup, base);
+        const openapiMetaTag = buildOpenApiMetaTag({
+            filePath: openApiFilePathFromRoot,
+            method: 'webhook',
+            path: webhook,
+        });
+        const badge = resolveBadge(operation?.tags);
+        const xMintMetadata = badge !== undefined && xMint?.metadata?.tag === undefined
+            ? { ...xMint?.metadata, tag: badge }
+            : xMint?.metadata;
+        const page = {
+            title: slugToTitle(filenameWithoutExtension),
+            description: operation?.description,
+            version: options.version,
+            deprecated: operation?.deprecated,
+            ...xMintMetadata,
+            openapi: openapiMetaTag,
+            href: posix.resolve('/', filenameWithoutExtension),
+        };
+        if (!isHiddenOperation(operation)) {
+            navGroup.push(filenameWithoutExtension);
+            decoratedNavGroup.push(page);
+        }
+        pagesAcc[filenameWithoutExtension] = page;
+        generatedSlugs.push(filenameWithoutExtension);
+        if (!options.writeFiles) {
+            registerXMintContent(filenameWithoutExtension, xMint?.content);
+        }
+        const targetPath = options.outDirBasePath
+            ? join(options.outDirBasePath, `${filenameWithoutExtension}.mdx`)
+            : `${filenameWithoutExtension}.mdx`;
+        if (options.writeFiles && (!fse.pathExistsSync(targetPath) || options.overwrite)) {
+            const input = {
+                openApiMetaTag: openapiMetaTag,
                 version: options.version,
                 deprecated: operation?.deprecated,
-                ...xMint?.metadata,
-                openapi: openapiMetaTag,
-                href: posix.resolve('/', filenameWithoutExtension),
+                metadata: xMintMetadata,
+                extraContent: xMint?.content,
             };
-            if (!isHiddenOperation(operation)) {
-                navGroup.push(filenameWithoutExtension);
-                decoratedNavGroup.push(page);
-            }
-            pagesAcc[filenameWithoutExtension] = page;
-            generatedSlugs.push(filenameWithoutExtension);
-            if (!options.writeFiles) {
-                registerXMintContent(filenameWithoutExtension, xMint?.content);
-            }
-            const targetPath = options.outDirBasePath
-                ? join(options.outDirBasePath, `${filenameWithoutExtension}.mdx`)
-                : `${filenameWithoutExtension}.mdx`;
-            if (options.writeFiles && (!fse.pathExistsSync(targetPath) || options.overwrite)) {
-                const input = {
-                    openApiMetaTag: openapiMetaTag,
-                    version: options.version,
-                    deprecated: operation?.deprecated,
-                    metadata: xMint?.metadata,
-                    extraContent: xMint?.content,
-                };
-                writePromises.push(options.writeFile
-                    ? Promise.resolve(options.writeFile(targetPath, createOpenApiFrontmatterContent(input)))
-                    : createOpenApiFrontmatter({ filename: targetPath, ...input }));
-            }
+            writePromises.push(options.writeFile
+                ? Promise.resolve(options.writeFile(targetPath, createOpenApiFrontmatterContent(input)))
+                : createOpenApiFrontmatter({ filename: targetPath, ...input }));
         }
     });
     return generatedSlugs;