@vercube/schema 0.0.48 → 1.0.0-beta.2

package/README.md

@@ -12,7 +12,7 @@
 ![GitHub License](<https://img.shields.io/github/license/vercube/vercube?style=for-the-badge&logo=gitbook&logoColor=rgba(255%2C%20255%2C%20255%2C%200.6)&labelColor=%23000&color=%232f2f2f>)
 ![Codecov](<https://img.shields.io/codecov/c/github/vercube/vercube?style=for-the-badge&logo=vitest&logoColor=rgba(255%2C%20255%2C%20255%2C%200.6)&labelColor=%23000&color=%232f2f2f>)
 
-**Auto-generate OpenAPI specs from your Zod schemas. Add `@Schema` to your routes, get Swagger docs at `/_schema`.**
+**Auto-generate OpenAPI specs from your Zod schemas. Add `@Schema` to your routes, get OpenAPI at `/_schema` and Scalar docs at `/_schema/docs`.**
 
 [Website](https://vercube.dev) • [Documentation](https://vercube.dev/docs/getting-started)
 
@@ -24,6 +24,7 @@
 - **Decorator API** - `@Schema` on routes to add OpenAPI metadata
 - **Auto-resolution** - picks up `@Body`, `@Param`, `@QueryParams` automatically
 - **Runtime endpoint** - OpenAPI JSON available at `/_schema`
+- **Scalar UI** - Interactive API docs at `/_schema/docs` ([Scalar](https://github.com/scalar/scalar))
 
 ## 📦 Installation
 

package/dist/index.d.mts

@@ -1,6 +1,7 @@
 import { RouteConfig } from "@asteasolutions/zod-to-openapi";
 import { z } from "zod";
 import { App, BasePlugin } from "@vercube/core";
+import { HtmlRenderingConfiguration } from "@scalar/client-side-rendering";
 
 //#region src/Decorators/Schema.d.ts
 interface SchemaDecoratorOptions extends Omit<RouteConfig, 'method' | 'path'> {}
@@ -15,6 +16,35 @@ interface SchemaDecoratorOptions extends Omit<RouteConfig, 'method' | 'path'> {}
  */
 declare function Schema(params: SchemaDecoratorOptions): Function;
 //#endregion
+//#region src/Types/SchemaPluginOptions.d.ts
+/**
+ * Scalar API Reference options (see https://github.com/scalar/scalar).
+ */
+interface SchemaScalarOptions {
+  /**
+   * OpenAPI document URL passed to Scalar.
+   * @default '/_schema/'
+   */
+  openApiUrl?: string;
+  /** HTML page title. @default 'API Reference' */
+  pageTitle?: string;
+  /** CDN URL for the Scalar bundle. Uses Scalar default when omitted. */
+  cdn?: string;
+  /** Additional Scalar configuration (theme, layout, etc.). */
+  config?: Partial<HtmlRenderingConfiguration>;
+}
+/**
+ * Options for {@link SchemaPlugin}.
+ */
+interface SchemaPluginOptions {
+  /**
+   * Scalar API Reference UI served at `/_schema/docs`.
+   * Pass `false` to disable.
+   * @default enabled with OpenAPI at `/_schema/`
+   */
+  scalar?: false | SchemaScalarOptions;
+}
+//#endregion
 //#region src/Plugins/SchemaPlugin.d.ts
 /**
  * Schema Plugin for Vercube framework
@@ -23,6 +53,7 @@ declare function Schema(params: SchemaDecoratorOptions): Function;
  * - Automatic OpenAPI schema generation from Zod schemas
  * - Route-level schema validation via @Schema decorator
  * - Runtime schema access via /_schema endpoint
+ * - Scalar API Reference UI at /_schema/docs (https://github.com/scalar/scalar)
  * - Seamless integration with request validation (@Body, @Query, etc)
  *
  * @example
@@ -39,7 +70,7 @@ declare function Schema(params: SchemaDecoratorOptions): Function;
  *
  * @see {@link https://vercube.dev} for full documentation
  */
-declare class SchemaPlugin<T = unknown> extends BasePlugin<T> {
+declare class SchemaPlugin extends BasePlugin<SchemaPluginOptions> {
   /**
    * The name of the plugin.
    * @override
@@ -51,7 +82,7 @@ declare class SchemaPlugin<T = unknown> extends BasePlugin<T> {
    * @returns {void | Promise<void>}
    * @override
    */
-  use(app: App, options: T): void | Promise<void>;
+  use(app: App, options?: SchemaPluginOptions): void | Promise<void>;
 }
 //#endregion
-export { Schema, SchemaPlugin, z };
+export { Schema, SchemaPlugin, type SchemaPluginOptions, type SchemaScalarOptions, z };

package/dist/index.mjs

@@ -1,8 +1,9 @@
 import { OpenAPIRegistry, OpenApiGeneratorV3, extendZodWithOpenApi } from "@asteasolutions/zod-to-openapi";
 import { z } from "zod";
-import { BaseDecorator, Inject, createDecorator } from "@vercube/di";
-import defu from "defu";
+import { BaseDecorator, Identity, Inject, createDecorator } from "@vercube/di";
+import defu$1, { defu } from "defu";
 import { BasePlugin, Controller, Get } from "@vercube/core";
+import { renderApiReference } from "@scalar/client-side-rendering";
 //#region src/Resolvers/SchemaBodyResolver.ts
 /**
 * Resolves the body schema for a given method.
@@ -13,7 +14,7 @@ import { BasePlugin, Controller, Get } from "@vercube/core";
 function SchemaBodyResolver(metadata, schema) {
 	const body = metadata.args.find((arg) => arg.type === "body");
 	if (!body || !body.validationSchema) return;
-	schema.request = defu(schema?.request ?? {}, { body: { content: { "application/json": { schema: body.validationSchema } } } });
+	schema.request = defu$1(schema?.request ?? {}, { body: { content: { "application/json": { schema: body.validationSchema } } } });
 }
 //#endregion
 //#region src/Resolvers/SchemaQueryParamsResolver.ts
@@ -26,7 +27,7 @@ function SchemaBodyResolver(metadata, schema) {
 function SchemaQueryParamsResolver(metadata, schema) {
 	const query = metadata.args.find((arg) => arg.type === "query-params");
 	if (!query || !query.validationSchema) return;
-	schema.request = defu(schema?.request ?? {}, { query: query.validationSchema });
+	schema.request = defu$1(schema?.request ?? {}, { query: query.validationSchema });
 }
 //#endregion
 //#region src/Services/SchemaRegistry.ts
@@ -67,7 +68,7 @@ var SchemaRegistry = class {
 	}
 };
 //#endregion
-//#region \0@oxc-project+runtime@0.130.0/helpers/decorate.js
+//#region \0@oxc-project+runtime@0.134.0/helpers/esm/decorate.js
 function __decorate(decorators, target, key, desc) {
 	var c = arguments.length, r = c < 3 ? target : desc === null ? desc = Object.getOwnPropertyDescriptor(target, key) : desc, d;
 	if (typeof Reflect === "object" && typeof Reflect.decorate === "function") r = Reflect.decorate(decorators, target, key, desc);
@@ -114,9 +115,19 @@ function Schema(params) {
 	return createDecorator(SchemaDecorator, params);
 }
 //#endregion
+//#region src/Constants/SchemaDefaults.ts
+const DEFAULT_SCHEMA_PLUGIN_OPTIONS = { scalar: {
+	openApiUrl: "/_schema/",
+	pageTitle: "API Reference"
+} };
+//#endregion
+//#region src/Symbols/SchemaSymbols.ts
+const $SchemaPluginOptions = Identity("SchemaPluginOptions");
+//#endregion
 //#region src/Controllers/SchameController.ts
 let SchemaController = class SchemaController {
 	gSchemaRegistry;
+	gSchemaPluginOptions;
 	/**
 	* Handles GET requests to retrieve the generated OpenAPI schema.
 	*
@@ -125,9 +136,35 @@ let SchemaController = class SchemaController {
 	async get() {
 		return this.gSchemaRegistry.generateSchema();
 	}
+	/**
+	* Serves the Scalar API Reference UI for the generated OpenAPI schema.
+	*
+	* @see https://github.com/scalar/scalar
+	*/
+	getDocs() {
+		if (this.gSchemaPluginOptions.scalar === false) return new Response(null, { status: 404 });
+		const scalar = {
+			...DEFAULT_SCHEMA_PLUGIN_OPTIONS.scalar,
+			...typeof this.gSchemaPluginOptions.scalar === "object" ? this.gSchemaPluginOptions.scalar : {}
+		};
+		const html = renderApiReference({
+			config: {
+				url: scalar.openApiUrl ?? "/_schema/",
+				...scalar.config
+			},
+			pageTitle: scalar.pageTitle,
+			cdn: scalar.cdn
+		});
+		return new Response(html, {
+			status: 200,
+			headers: { "Content-Type": "text/html; charset=utf-8" }
+		});
+	}
 };
 __decorate([Inject(SchemaRegistry)], SchemaController.prototype, "gSchemaRegistry", void 0);
+__decorate([Inject($SchemaPluginOptions)], SchemaController.prototype, "gSchemaPluginOptions", void 0);
 __decorate([Get("/")], SchemaController.prototype, "get", null);
+__decorate([Get("/docs")], SchemaController.prototype, "getDocs", null);
 SchemaController = __decorate([Controller("/_schema")], SchemaController);
 //#endregion
 //#region src/Plugins/SchemaPlugin.ts
@@ -138,6 +175,7 @@ SchemaController = __decorate([Controller("/_schema")], SchemaController);
 * - Automatic OpenAPI schema generation from Zod schemas
 * - Route-level schema validation via @Schema decorator
 * - Runtime schema access via /_schema endpoint
+* - Scalar API Reference UI at /_schema/docs (https://github.com/scalar/scalar)
 * - Seamless integration with request validation (@Body, @Query, etc)
 *
 * @example
@@ -167,6 +205,8 @@ var SchemaPlugin = class extends BasePlugin {
 	* @override
 	*/
 	use(app, options) {
+		const mergedOptions = defu(options ?? {}, DEFAULT_SCHEMA_PLUGIN_OPTIONS);
+		app.container.bindInstance($SchemaPluginOptions, mergedOptions);
 		app.container.bind(SchemaRegistry);
 		app.container.bind(SchemaController);
 	}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@vercube/schema",
-  "version": "0.0.48",
+  "version": "1.0.0-beta.2",
   "description": "Schema (swagger) module for Vercube framework",
   "repository": {
     "type": "git",
@@ -28,11 +28,12 @@
   ],
   "dependencies": {
     "@asteasolutions/zod-to-openapi": "8.5.0",
+    "@scalar/client-side-rendering": "0.2.3",
     "@standard-schema/spec": "1.1.0",
     "defu": "6.1.7",
     "zod": "4.4.3",
-    "@vercube/di": "0.0.48",
-    "@vercube/core": "0.0.48"
+    "@vercube/core": "1.0.0-beta.2",
+    "@vercube/di": "1.0.0-beta.2"
   },
   "publishConfig": {
     "access": "public"