@velajs/vela 1.8.3 → 1.8.4

package/dist/openapi/document.js

@@ -241,6 +241,34 @@ export function createOpenApiDocument(rootModule, options = {}) {
             }
         }
     }
+    // Aggregate the document-root `tags` array. NestJS declares tag
+    // groups/descriptions/order via `DocumentBuilder().addTag(name, desc)`
+    // while its scanner auto-collects operation tags; we wire both halves
+    // here. Walk every operation's `tags` in first-seen order (stable: paths
+    // insertion order, then verb order), then merge with `options.tags`
+    // (caller-declared tags first — preserving their order + descriptions —
+    // followed by any purely-collected tag not already declared, as `{ name }`).
+    const seenTagNames = new Set();
+    const collectedTagNames = [];
+    for (const pathItem of Object.values(paths)){
+        for (const verb of VERB_WHITELIST){
+            const operation = pathItem[verb];
+            if (!operation?.tags) continue;
+            for (const tagName of operation.tags){
+                if (seenTagNames.has(tagName)) continue;
+                seenTagNames.add(tagName);
+                collectedTagNames.push(tagName);
+            }
+        }
+    }
+    const declaredTags = options.tags ?? [];
+    const declaredTagNames = new Set(declaredTags.map((t)=>t.name));
+    const tags = [
+        ...declaredTags,
+        ...collectedTagNames.filter((name)=>!declaredTagNames.has(name)).map((name)=>({
+                name
+            }))
+    ];
     const document = {
         openapi: '3.1.0',
         info: {
@@ -258,5 +286,11 @@ export function createOpenApiDocument(rootModule, options = {}) {
             schemas
         };
     }
+    // Only attach `tags` when non-empty. Emitting `tags: []` on a tag-less
+    // spec is the exact symptom the consumer reported, so omit the key
+    // entirely in that case (mirrors the `components` handling above).
+    if (tags.length > 0) {
+        document.tags = tags;
+    }
     return document;
 }

package/dist/openapi/types.d.ts

@@ -90,6 +90,17 @@ export interface ApiResponseEntry extends ApiResponseOptions {
 export interface CreateOpenApiDocumentOptions {
     info?: Partial<OpenApiInfo>;
     globalPrefix?: string;
+    /**
+     * Declare top-level tag groups with descriptions and an explicit order
+     * (mirrors NestJS `DocumentBuilder().addTag(name, description)`). Tags
+     * actually used by operations but NOT declared here are still emitted —
+     * appended after the declared ones in first-seen order. Declared tags
+     * with no operations are kept (lets you pre-declare ordering/description).
+     */
+    tags?: Array<{
+        name: string;
+        description?: string;
+    }>;
 }
 export interface MountOpenApiOptions {
     /** Pre-built OpenAPI document to serve. */

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@velajs/vela",
-  "version": "1.8.3",
+  "version": "1.8.4",
   "description": "NestJS-compatible framework for edge runtimes, powered by Hono",
   "type": "module",
   "main": "./dist/index.js",