@velajs/vela 1.8.3 → 1.8.5

package/dist/application.d.ts

@@ -24,13 +24,20 @@ export declare class VelaApplication {
     useGlobalInterceptors(...interceptors: InterceptorType[]): this;
     useGlobalFilters(...filters: FilterType[]): this;
     /**
-     * Serve a pre-built OpenAPI document (and optionally a Scalar UI) on
-     * the underlying Hono app. Edge-safe: the UI HTML loads Scalar from a
-     * CDN at runtime so nothing is bundled server-side.
+     * Serve a pre-built OpenAPI document and one or more interactive doc UIs
+     * (Swagger UI, Scalar, ReDoc) on the underlying Hono app, mirroring the
+     * hono-crud docs convention. Edge-safe: each UI is a tiny self-contained
+     * HTML shell that loads its renderer from a CDN at runtime so nothing is
+     * bundled server-side and no extra dependency is required.
+     *
+     * Defaults: spec at `/openapi.json`, Scalar at `/scalar`, Swagger UI at
+     * `/docs`, ReDoc at `/redoc`. The deprecated `path` / `uiPath` aliases are
+     * retained for migration from the previous single-UI shape.
      *
      * ```ts
      * const doc = createOpenApiDocument(AppModule);
-     * app.mountOpenApi({ document: doc, ui: 'scalar' });
+     * app.mountOpenApi({ document: doc });            // Scalar @ /scalar
+     * app.mountOpenApi({ document: doc, ui: 'all' }); // swagger + scalar + redoc
      * ```
      */
     mountOpenApi(options: MountOpenApiOptions): this;

package/dist/application.js

@@ -1,5 +1,7 @@
 import { hasBeforeApplicationShutdown, hasOnApplicationBootstrap, hasOnApplicationShutdown, hasOnModuleDestroy, hasOnModuleInit } from "./lifecycle/index.js";
 import { renderScalarUi } from "./openapi/scalar-ui.js";
+import { renderSwaggerUi } from "./openapi/swagger-ui.js";
+import { renderRedocUi } from "./openapi/redoc-ui.js";
 export class VelaApplication {
     container;
     routeManager;
@@ -54,23 +56,69 @@ export class VelaApplication {
         return this;
     }
     /**
-   * Serve a pre-built OpenAPI document (and optionally a Scalar UI) on
-   * the underlying Hono app. Edge-safe: the UI HTML loads Scalar from a
-   * CDN at runtime so nothing is bundled server-side.
+   * Serve a pre-built OpenAPI document and one or more interactive doc UIs
+   * (Swagger UI, Scalar, ReDoc) on the underlying Hono app, mirroring the
+   * hono-crud docs convention. Edge-safe: each UI is a tiny self-contained
+   * HTML shell that loads its renderer from a CDN at runtime so nothing is
+   * bundled server-side and no extra dependency is required.
+   *
+   * Defaults: spec at `/openapi.json`, Scalar at `/scalar`, Swagger UI at
+   * `/docs`, ReDoc at `/redoc`. The deprecated `path` / `uiPath` aliases are
+   * retained for migration from the previous single-UI shape.
    *
    * ```ts
    * const doc = createOpenApiDocument(AppModule);
-   * app.mountOpenApi({ document: doc, ui: 'scalar' });
+   * app.mountOpenApi({ document: doc });            // Scalar @ /scalar
+   * app.mountOpenApi({ document: doc, ui: 'all' }); // swagger + scalar + redoc
    * ```
    */ mountOpenApi(options) {
         const app = this.getApp();
-        const jsonPath = options.path ?? '/docs.json';
         const doc = options.document;
-        app.get(jsonPath, (c)=>c.json(doc));
-        if (options.ui === 'scalar') {
-            const uiPath = options.uiPath ?? '/docs';
-            const html = renderScalarUi(jsonPath);
-            app.get(uiPath, (c)=>c.html(html));
+        const title = options.title;
+        // Spec JSON: new default `/openapi.json`. The deprecated `path` alias is
+        // honored as an override only (does not change the default).
+        const specPath = options.specPath ?? options.path ?? '/openapi.json';
+        app.get(specPath, (c)=>c.json(doc));
+        // Normalize the requested UI set. Default is Scalar only.
+        const uiOption = options.ui;
+        let uis;
+        let singleStringUi = false;
+        if (uiOption === undefined) {
+            uis = [
+                'scalar'
+            ];
+        } else if (uiOption === 'all') {
+            uis = [
+                'swagger',
+                'scalar',
+                'redoc'
+            ];
+        } else if (Array.isArray(uiOption)) {
+            uis = uiOption;
+        } else {
+            uis = [
+                uiOption
+            ];
+            singleStringUi = true;
+        }
+        for (const ui of uis){
+            // Back-compat: the old `{ ui: 'scalar', uiPath }` form mapped a single
+            // string UI to `uiPath`. Honor that only when exactly one UI was
+            // requested as a string.
+            const legacyPath = singleStringUi && uis.length === 1 ? options.uiPath : undefined;
+            if (ui === 'swagger') {
+                const path = legacyPath ?? options.swaggerPath ?? '/docs';
+                const html = renderSwaggerUi(specPath, title);
+                app.get(path, (c)=>c.html(html));
+            } else if (ui === 'redoc') {
+                const path = legacyPath ?? options.redocPath ?? '/redoc';
+                const html = renderRedocUi(specPath, title);
+                app.get(path, (c)=>c.html(html));
+            } else {
+                const path = legacyPath ?? options.scalarPath ?? '/scalar';
+                const html = renderScalarUi(specPath, title);
+                app.get(path, (c)=>c.html(html));
+            }
         }
         return this;
     }

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/index.d.ts

@@ -2,4 +2,6 @@ export { createOpenApiDocument } from './document';
 export { ApiDoc, ApiTags, ApiResponse, API_DOC_METADATA, API_TAGS_METADATA, API_RESPONSES_METADATA, } from './decorators';
 export { zodToJsonSchema } from './zod-to-json-schema';
 export { renderScalarUi } from './scalar-ui';
-export type { ApiDocMetadata, ApiResponseEntry, ApiResponseOptions, CreateOpenApiDocumentOptions, HttpVerb, JsonSchema, MountOpenApiOptions, OpenApiDocument, OpenApiInfo, OpenApiOperation, OpenApiParameter, OpenApiPathItem, OpenApiRequestBody, OpenApiResponse, } from './types';
+export { renderSwaggerUi } from './swagger-ui';
+export { renderRedocUi } from './redoc-ui';
+export type { ApiDocMetadata, ApiResponseEntry, ApiResponseOptions, CreateOpenApiDocumentOptions, HttpVerb, JsonSchema, MountOpenApiOptions, OpenApiUi, OpenApiDocument, OpenApiInfo, OpenApiOperation, OpenApiParameter, OpenApiPathItem, OpenApiRequestBody, OpenApiResponse, } from './types';

package/dist/openapi/index.js

@@ -2,3 +2,5 @@ export { createOpenApiDocument } from "./document.js";
 export { ApiDoc, ApiTags, ApiResponse, API_DOC_METADATA, API_TAGS_METADATA, API_RESPONSES_METADATA } from "./decorators.js";
 export { zodToJsonSchema } from "./zod-to-json-schema.js";
 export { renderScalarUi } from "./scalar-ui.js";
+export { renderSwaggerUi } from "./swagger-ui.js";
+export { renderRedocUi } from "./redoc-ui.js";

package/dist/openapi/redoc-ui.d.ts

@@ -0,0 +1 @@
+export declare function renderRedocUi(specUrl: string, title?: string): string;

package/dist/openapi/redoc-ui.js

@@ -0,0 +1,19 @@
+// Minimal HTML shell that bootstraps ReDoc from a CDN. Served as a static
+// string so it works on every edge runtime with no Node or bundler deps —
+// ReDoc itself is loaded from a CDN at runtime.
+export function renderRedocUi(specUrl, title) {
+    const safeUrl = specUrl.replace(/"/g, '"');
+    const safeTitle = (title ?? 'API Reference').replace(/&/g, '&amp;').replace(/</g, '&lt;').replace(/>/g, '&gt;');
+    return `<!doctype html>
+<html>
+  <head>
+    <title>${safeTitle}</title>
+    <meta charset="utf-8" />
+    <meta name="viewport" content="width=device-width, initial-scale=1" />
+  </head>
+  <body>
+    <redoc spec-url="${safeUrl}"></redoc>
+    <script src="https://cdn.jsdelivr.net/npm/redoc/bundles/redoc.standalone.js"></script>
+  </body>
+</html>`;
+}

package/dist/openapi/scalar-ui.d.ts

@@ -1 +1 @@
-export declare function renderScalarUi(jsonUrl: string): string;
+export declare function renderScalarUi(jsonUrl: string, title?: string): string;

package/dist/openapi/scalar-ui.js

@@ -1,12 +1,13 @@
 // Minimal HTML shell that bootstraps Scalar's hosted API-reference UI.
 // Served as a static string so it works on every edge runtime with no
 // Node or bundler deps. Scalar itself is loaded from a CDN at runtime.
-export function renderScalarUi(jsonUrl) {
+export function renderScalarUi(jsonUrl, title) {
     const safeUrl = jsonUrl.replace(/"/g, '"');
+    const safeTitle = (title ?? 'API Reference').replace(/&/g, '&amp;').replace(/</g, '&lt;').replace(/>/g, '&gt;');
     return `<!doctype html>
 <html>
   <head>
-    <title>API Reference</title>
+    <title>${safeTitle}</title>
     <meta charset="utf-8" />
     <meta name="viewport" content="width=device-width, initial-scale=1" />
   </head>

package/dist/openapi/swagger-ui.d.ts

@@ -0,0 +1 @@
+export declare function renderSwaggerUi(specUrl: string, title?: string): string;

package/dist/openapi/swagger-ui.js

@@ -0,0 +1,23 @@
+// Minimal HTML shell that bootstraps Swagger UI from a CDN. Served as a
+// static string so it works on every edge runtime with no Node or bundler
+// deps — Swagger UI itself is loaded from a CDN at runtime.
+export function renderSwaggerUi(specUrl, title) {
+    const safeUrl = specUrl.replace(/"/g, '"');
+    const safeTitle = (title ?? 'API Reference').replace(/&/g, '&amp;').replace(/</g, '&lt;').replace(/>/g, '&gt;');
+    return `<!doctype html>
+<html>
+  <head>
+    <title>${safeTitle}</title>
+    <meta charset="utf-8" />
+    <meta name="viewport" content="width=device-width, initial-scale=1" />
+    <link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/swagger-ui-dist/swagger-ui.css" />
+  </head>
+  <body>
+    <div id="swagger-ui"></div>
+    <script src="https://cdn.jsdelivr.net/npm/swagger-ui-dist/swagger-ui-bundle.js"></script>
+    <script>
+      window.ui = SwaggerUIBundle({ url: "${safeUrl}", dom_id: '#swagger-ui' });
+    </script>
+  </body>
+</html>`;
+}

package/dist/openapi/types.d.ts

@@ -90,14 +90,39 @@ 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 type OpenApiUi = 'swagger' | 'scalar' | 'redoc';
 export interface MountOpenApiOptions {
     /** Pre-built OpenAPI document to serve. */
     document: OpenApiDocument;
-    /** Path for the JSON endpoint. Default `/docs.json`. */
+    /** OpenAPI JSON spec path. @default '/openapi.json' */
+    specPath?: string;
+    /**
+     * UI(s) to mount. 'all' mounts swagger + scalar + redoc.
+     * @default 'scalar'
+     */
+    ui?: OpenApiUi | OpenApiUi[] | 'all';
+    /** Swagger UI path. @default '/docs' */
+    swaggerPath?: string;
+    /** Scalar path. @default '/scalar' */
+    scalarPath?: string;
+    /** ReDoc path. @default '/redoc' */
+    redocPath?: string;
+    /** Page title for the UIs. */
+    title?: string;
+    /** @deprecated use `specPath`. Back-compat alias; if set, overrides specPath default. */
     path?: string;
-    /** Opt-in UI renderer. Only `scalar` is bundled today. */
-    ui?: 'scalar';
-    /** Path the UI is served at when `ui` is set. Default `/docs`. */
+    /** @deprecated single-UI path override; applies to the single `ui` when a string. */
     uiPath?: string;
 }

package/package.json

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