nestjs-openapi-next 1.0.3 → 1.0.4

package/README.md

@@ -100,7 +100,7 @@ This fork treats tag `summary` and `x-displayName` as equivalent display fields:
 
 #### Auto-derived (recommended)
 
-If you use tag `parent` relationships (via `@ApiTag()`), the root-level `x-tagGroups` will be derived automatically:
+If you use tag `parent` relationships (via `@ApiTag()`), the root-level `x-tagGroups` will be derived automatically (both in the scanned output and in the final document), so downstream generators (e.g. `.tags`) can render grouped tags correctly:
 
 ```ts
 @ApiTag({ name: 'Customers' })

package/dist/swagger-module.d.ts

@@ -3,7 +3,6 @@ import { HttpServer } from '@nestjs/common/interfaces/http/http-server.interface
 import { OpenAPIObject, SwaggerCustomOptions, SwaggerDocumentOptions } from './interfaces';
 export declare class SwaggerModule {
     private static readonly metadataLoader;
-    private static readonly HTTP_METHODS;
     private static collectOperationTagNames;
     private static mergeWebhooks;
     private static mergeTags;

package/dist/swagger-module.js

@@ -21,6 +21,8 @@ const normalize_rel_path_1 = require("./utils/normalize-rel-path");
 const resolve_path_util_1 = require("./utils/resolve-path.util");
 const validate_global_prefix_util_1 = require("./utils/validate-global-prefix.util");
 const validate_path_util_1 = require("./utils/validate-path.util");
+const build_x_tag_groups_util_1 = require("./utils/build-x-tag-groups.util");
+const collect_operation_tag_names_util_1 = require("./utils/collect-operation-tag-names.util");
 const NULL_TYPE_SCHEMA = { type: 'null' };
 function isReferenceObject(value) {
     return !!(value === null || value === void 0 ? void 0 : value.$ref);
@@ -321,41 +323,7 @@ function normalizeNullableForOas31(document) {
 }
 class SwaggerModule {
     static collectOperationTagNames(paths, webhooks) {
-        const names = [];
-        const seen = new Set();
-        const collectFromItems = (items) => {
-            if (!items) {
-                return;
-            }
-            for (const pathItem of Object.values(items)) {
-                if (!pathItem || typeof pathItem !== 'object') {
-                    continue;
-                }
-                for (const [key, operation] of Object.entries(pathItem)) {
-                    if (!SwaggerModule.HTTP_METHODS.has(String(key).toLowerCase())) {
-                        continue;
-                    }
-                    const tags = operation === null || operation === void 0 ? void 0 : operation.tags;
-                    if (!Array.isArray(tags)) {
-                        continue;
-                    }
-                    for (const t of tags) {
-                        if (typeof t !== 'string') {
-                            continue;
-                        }
-                        const trimmed = t.trim();
-                        if (!trimmed || seen.has(trimmed)) {
-                            continue;
-                        }
-                        seen.add(trimmed);
-                        names.push(trimmed);
-                    }
-                }
-            }
-        };
-        collectFromItems(paths);
-        collectFromItems(webhooks);
-        return names;
+        return (0, collect_operation_tag_names_util_1.collectOperationTagNames)(paths, webhooks);
     }
     static mergeWebhooks(configWebhooks, scannedWebhooks) {
         if (!configWebhooks && !scannedWebhooks) {
@@ -401,55 +369,8 @@ class SwaggerModule {
         const merged = [...byName.values()];
         return merged.length > 0 ? merged : undefined;
     }
-    static buildXTagGroups(tags) {
-        if (!tags || tags.length === 0) {
-            return undefined;
-        }
-        const groupToTags = new Map();
-        const groupToSeen = new Map();
-        for (const tag of tags) {
-            const parent = tag.parent;
-            if (!parent) {
-                continue;
-            }
-            if (!groupToTags.has(parent)) {
-                groupToTags.set(parent, []);
-                groupToSeen.set(parent, new Set());
-            }
-            let list = groupToTags.get(parent);
-            if (!list) {
-                list = [];
-                groupToTags.set(parent, list);
-            }
-            let seen = groupToSeen.get(parent);
-            if (!seen) {
-                seen = new Set();
-                groupToSeen.set(parent, seen);
-            }
-            if (!seen.has(tag.name)) {
-                seen.add(tag.name);
-                list.push(tag.name);
-            }
-        }
-        if (groupToTags.size === 0) {
-            return undefined;
-        }
-        const allTagNames = new Set(tags.map((t) => t.name));
-        return [...groupToTags.entries()].map(([name, childTags]) => {
-            const finalTags = [];
-            const seen = new Set();
-            if (allTagNames.has(name)) {
-                seen.add(name);
-                finalTags.push(name);
-            }
-            for (const t of childTags) {
-                if (!seen.has(t)) {
-                    seen.add(t);
-                    finalTags.push(t);
-                }
-            }
-            return { name, tags: finalTags };
-        });
+    static buildXTagGroups(tags, operationTagNames) {
+        return (0, build_x_tag_groups_util_1.buildXTagGroups)(tags, operationTagNames);
     }
     static createDocument(app, config, options = {}) {
         const swaggerScanner = new swagger_scanner_1.SwaggerScanner();
@@ -463,7 +384,7 @@ class SwaggerModule {
             normalizeNullableForOas31(mergedDocument);
         }
         if (mergedDocument['x-tagGroups'] === undefined) {
-            const xTagGroups = SwaggerModule.buildXTagGroups(mergedDocument.tags);
+            const xTagGroups = SwaggerModule.buildXTagGroups(mergedDocument.tags, operationTagNames);
             if (xTagGroups) {
                 mergedDocument['x-tagGroups'] = xTagGroups;
             }
@@ -636,13 +557,3 @@ class SwaggerModule {
 }
 exports.SwaggerModule = SwaggerModule;
 SwaggerModule.metadataLoader = new metadata_loader_1.MetadataLoader();
-SwaggerModule.HTTP_METHODS = new Set([
-    'get',
-    'put',
-    'post',
-    'delete',
-    'options',
-    'head',
-    'patch',
-    'trace'
-]);

package/dist/swagger-scanner.js

@@ -11,6 +11,8 @@ const swagger_explorer_1 = require("./swagger-explorer");
 const swagger_transformer_1 = require("./swagger-transformer");
 const get_global_prefix_1 = require("./utils/get-global-prefix");
 const strip_last_slash_util_1 = require("./utils/strip-last-slash.util");
+const build_x_tag_groups_util_1 = require("./utils/build-x-tag-groups.util");
+const collect_operation_tag_names_util_1 = require("./utils/collect-operation-tag-names.util");
 class SwaggerScanner {
     constructor() {
         this.transformer = new swagger_transformer_1.SwaggerTransformer();
@@ -56,7 +58,10 @@ class SwaggerScanner {
         });
         const schemas = this.explorer.getSchemas();
         this.addExtraModels(schemas, extraModels);
-        return Object.assign(Object.assign(Object.assign({}, this.transformer.normalizePaths((0, lodash_1.flatten)(denormalizedPaths))), (tagGroups.length > 0 ? { tags: tagGroups } : {})), { components: {
+        const normalized = this.transformer.normalizePaths((0, lodash_1.flatten)(denormalizedPaths));
+        const operationTagNames = (0, collect_operation_tag_names_util_1.collectOperationTagNames)(normalized.paths, normalized.webhooks);
+        const xTagGroups = (0, build_x_tag_groups_util_1.buildXTagGroups)(tagGroups, operationTagNames);
+        return Object.assign(Object.assign(Object.assign(Object.assign({}, normalized), (tagGroups.length > 0 ? { tags: tagGroups } : {})), (xTagGroups ? { 'x-tagGroups': xTagGroups } : {})), { components: {
                 schemas: schemas
             } });
     }

package/dist/utils/build-x-tag-groups.util.d.ts

@@ -0,0 +1,5 @@
+import { TagObject } from '../interfaces/open-api-spec.interface';
+export declare function buildXTagGroups(tags?: TagObject[], operationTagNames?: string[]): {
+    name: string;
+    tags: string[];
+}[];

package/dist/utils/build-x-tag-groups.util.js

@@ -0,0 +1,68 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.buildXTagGroups = buildXTagGroups;
+function buildXTagGroups(tags, operationTagNames) {
+    const opNames = new Set((operationTagNames || [])
+        .filter((t) => typeof t === 'string')
+        .map((t) => t.trim())
+        .filter(Boolean));
+    if ((!tags || tags.length === 0) && opNames.size === 0) {
+        return undefined;
+    }
+    const groupToChildTags = new Map();
+    const groupToSeen = new Map();
+    const childToParent = new Map();
+    for (const tag of tags || []) {
+        const parent = tag.parent;
+        if (!parent) {
+            continue;
+        }
+        childToParent.set(tag.name, parent);
+        if (!groupToChildTags.has(parent)) {
+            groupToChildTags.set(parent, []);
+            groupToSeen.set(parent, new Set());
+        }
+        let list = groupToChildTags.get(parent);
+        if (!list) {
+            list = [];
+            groupToChildTags.set(parent, list);
+        }
+        let seen = groupToSeen.get(parent);
+        if (!seen) {
+            seen = new Set();
+            groupToSeen.set(parent, seen);
+        }
+        if (!seen.has(tag.name)) {
+            seen.add(tag.name);
+            list.push(tag.name);
+        }
+    }
+    for (const name of opNames) {
+        if (childToParent.has(name)) {
+            continue;
+        }
+        if (!groupToChildTags.has(name)) {
+            groupToChildTags.set(name, []);
+            groupToSeen.set(name, new Set());
+        }
+    }
+    if (groupToChildTags.size === 0) {
+        return undefined;
+    }
+    const allTagNames = new Set((tags || []).map((t) => t.name));
+    return [...groupToChildTags.entries()].map(([name, childTags]) => {
+        const finalTags = [];
+        const seen = new Set();
+        if (allTagNames.has(name) || opNames.has(name)) {
+            seen.add(name);
+            finalTags.push(name);
+        }
+        for (const t of childTags) {
+            if (!seen.has(t)) {
+                seen.add(t);
+                finalTags.push(t);
+            }
+        }
+        return { name, tags: finalTags };
+    });
+}

package/dist/utils/collect-operation-tag-names.util.d.ts

@@ -0,0 +1,2 @@
+import { OpenAPIObject } from '../interfaces/open-api-spec.interface';
+export declare function collectOperationTagNames(paths?: OpenAPIObject['paths'], webhooks?: OpenAPIObject['webhooks']): string[];

package/dist/utils/collect-operation-tag-names.util.js

@@ -0,0 +1,52 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.collectOperationTagNames = collectOperationTagNames;
+const HTTP_METHODS = new Set([
+    'get',
+    'put',
+    'post',
+    'delete',
+    'options',
+    'head',
+    'patch',
+    'trace',
+    'search',
+    'query'
+]);
+function collectOperationTagNames(paths, webhooks) {
+    const names = [];
+    const seen = new Set();
+    const collectFromItems = (items) => {
+        if (!items) {
+            return;
+        }
+        for (const pathItem of Object.values(items)) {
+            if (!pathItem || typeof pathItem !== 'object') {
+                continue;
+            }
+            for (const [key, operation] of Object.entries(pathItem)) {
+                if (!HTTP_METHODS.has(String(key).toLowerCase())) {
+                    continue;
+                }
+                const tags = operation === null || operation === void 0 ? void 0 : operation.tags;
+                if (!Array.isArray(tags)) {
+                    continue;
+                }
+                for (const t of tags) {
+                    if (typeof t !== 'string') {
+                        continue;
+                    }
+                    const trimmed = t.trim();
+                    if (!trimmed || seen.has(trimmed)) {
+                        continue;
+                    }
+                    seen.add(trimmed);
+                    names.push(trimmed);
+                }
+            }
+        }
+    };
+    collectFromItems(paths);
+    collectFromItems(webhooks);
+    return names;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "nestjs-openapi-next",
-  "version": "1.0.3",
+  "version": "1.0.4",
   "description": "A fork of @nestjs/swagger support OAS 3.2",
   "author": "undownding",
   "license": "MIT",