npm - @tahminator/sapling - Versions diffs - 2.0.5 → 2.1.0 - Mend

@tahminator/sapling 2.0.5 → 2.1.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (6) hide show

package/dist/index.cjs CHANGED Viewed

@@ -23,6 +23,8 @@ var __toESM = (mod, isNodeMode, target) => (target = mod != null ? __create(__ge
 //#endregion
 let express = require("express");
 express = __toESM(express);
+let swagger_ui_express = require("swagger-ui-express");
+swagger_ui_express = __toESM(swagger_ui_express);
 //#region src/html/404.ts
 /**
 * Default Express.js 404 error page, as a string.
@@ -46,6 +48,7 @@ const Html404ErrorPage = (error) => `<!DOCTYPE html>
 * You can either return `new RedirectView(url)` or `RedirectView.redirect(url)` inside of a controller method.
 */
 var RedirectView = class RedirectView {
+	_url;
 	constructor(url) {
 		this._url = url;
 	}
@@ -141,8 +144,10 @@ let HttpStatus = /* @__PURE__ */ function(HttpStatus) {
 * @typeParam T - the type of the response body
 */
 var ResponseEntity = class {
+	_statusCode;
+	_headers = {};
+	_body;
 	constructor(body, headers = {}, statusCode = 200) {
-		this._headers = {};
 		this._body = body;
 		this._headers = headers;
 		this._statusCode = statusCode;
@@ -195,8 +200,9 @@ var ResponseEntity = class {
 * ensuring type safety when constructing the response.
 */
 var ResponseEntityBuilder = class {
+	_statusCode;
+	_headers = {};
 	constructor(statusCode) {
-		this._headers = {};
 		this._statusCode = statusCode;
 	}
 	/**
@@ -228,6 +234,7 @@ var ResponseEntityBuilder = class {
 * @see {@link Sapling.loadResponseStatusErrorMiddleware}
 */
 var ResponseStatusError = class ResponseStatusError extends Error {
+	status;
 	constructor(status, message) {
 		super(message ?? "Something went wrong.");
 		this.status = status;
@@ -239,32 +246,42 @@ var ResponseStatusError = class ResponseStatusError extends Error {
 //#endregion
 //#region src/helper/error/parse.ts
 /**
-* This error should be thrown when some data cannot be parsed by a given schema.
+* This error should be thrown when some data cannot be parsed by a given Standard Schema compatible schema.
 */
 var ParserError = class ParserError extends ResponseStatusError {
-	constructor(location, issues, vendor) {
-		super(400, ParserError.formatMessage(location, issues, vendor));
+	constructor(location, issues, vendor, functionName) {
+		super(400, ParserError.formatMessage(location, issues, vendor, functionName));
 		Object.setPrototypeOf(this, new.target.prototype);
 	}
-	static formatMessage(location, issues, vendor) {
+	static formatMessage(location, issues, vendor, functionName) {
 		const formatted = issues.map((i) => {
 			const path = Array.isArray(i.path) ? i.path.map((seg) => typeof seg === "object" && seg ? String(seg.key) : String(seg)).join(".") : "";
 			return path ? `${path}: ${i.message}` : i.message;
 		}).join("; ");
-		return `${vendor} failed to parse ${(() => {
-			switch (location) {
-				case "reqbody": return "request body";
-				case "reqparams": return "request params";
-				case "reqquery": return "request query";
-			}
-		})()}: ${formatted}`;
+		return `Failed to parse ${this.getPrettyLocationString(location)} with ${vendor} on ${functionName}: ${formatted}`;
+	}
+	static getPrettyLocationString(location) {
+		switch (location) {
+			case "reqbody": return "request body";
+			case "reqparams": return "request params";
+			case "reqquery": return "request query";
+			case "resbody": return "response body";
+		}
 	}
 };
 //#endregion
 //#region src/helper/sapling.ts
-const settings = {
+const _settings = {
 	serialize: JSON.stringify,
-	deserialize: JSON.parse
+	deserialize: JSON.parse,
+	doc: {
+		openApiPath: "/openapi.json",
+		swaggerPath: "/swagger.html",
+		metadata: {
+			title: "API",
+			version: "1.0.0"
+		}
+	}
 };
 /**
 * Collection of utility functions which are essential for Sapling to function.
@@ -343,13 +360,13 @@ var Sapling = class Sapling {
 	* @defaultValue `JSON.stringify`
 	*/
 	static serialize(value) {
-		return settings.serialize(value);
+		return _settings.serialize(value);
 	}
 	/**
 	* Replace the function used for `serialize`.
 	*/
 	static setSerializeFn(fn) {
-		settings.serialize = fn;
+		_settings.serialize = fn;
 	}
 	/**
 	* De-serialize a JSON string back to a JavaScript object.
@@ -361,15 +378,389 @@ var Sapling = class Sapling {
 	* @defaultValue `JSON.parse`
 	*/
 	static deserialize(value) {
-		return settings.deserialize(value);
+		return _settings.deserialize(value);
 	}
 	/**
 	* Replace the function used for `deserialize`
 	*/
 	static setDeserializeFn(fn) {
-		settings.deserialize = fn;
+		_settings.deserialize = fn;
+	}
+	/**
+	* Modify extra settings
+	*/
+	static Extras = {
+	/**
+	* Modify default settings applied to OpenAPI & Swagger
+	*/
+swaggerAndOpenApi: {
+		/**
+		* Set base OpenAPI metadata values.
+		*
+		* @default { title: "API", version: "1.0.0" }
+		*/
+		setMetadata(metadata) {
+			_settings.doc.metadata = metadata;
+		},
+		/**
+		* change default endpoint that will serve OpenAPI spec.
+		* Swagger will also load this endpoint on load.
+		*
+		* @default `/openapi.json`
+		*/
+		setOpenApiPath(path) {
+			_settings.doc.openApiPath = path;
+		},
+		/**
+		* change Swagger endpoint.
+		*
+		* @default `/swagger.html`
+		*/
+		setSwaggerPath(path) {
+			_settings.doc.swaggerPath = path;
+		}
+	} };
+	/**
+	* This method can be used in a `@MiddlewareClass` to register any libraries
+	* that expect you to register multiple registers at once. An example is `swagger-ui-express`
+	*
+	* @example
+	* ```ts
+	* ⠀@MiddlewareClass()
+	*  class Serve {
+	*    // `swagger.serve` returns multiple Express handlers for all the assets and routes
+	*    // that will be served
+	*    private readonly handlers: RequestHandler[] = swagger.serve;
+	*
+	*   ⠀@Middleware(_settings.doc.swaggerPath)
+	*    handle(request: Request, response: Response, next: NextFunction) {
+	*      return Sapling.chainHandlers(this.handlers, request, response, next);
+	*    }
+	*  }
+	* ```
+	*/
+	static chainHandlers(handlers, request, response, next, index = 0) {
+		if (index >= handlers.length) {
+			next();
+			return;
+		}
+		handlers[index]?.(request, response, (err) => {
+			if (err) {
+				next(err);
+				return;
+			}
+			Sapling.chainHandlers(handlers, request, response, next, index + 1);
+		});
+	}
+};
+//#endregion
+//#region src/annotation/route.ts
+const _routeStore = /* @__PURE__ */ new WeakMap();
+/**
+* Custom annotation that will store all routes inside of a map,
+* which can then be used to initialize all the routes to the router.
+*/
+function _Route({ method, path = "" }) {
+	return (target, propertyKey) => {
+		const ctor = target.constructor;
+		const list = _routeStore.get(ctor) ?? [];
+		list.push({
+			method,
+			path: path ?? "",
+			fnName: String(propertyKey)
+		});
+		_routeStore.set(ctor, list);
+	};
+}
+/**
+* Register GET route on the given path (default "") for the given controller.
+*/
+const GET = (path = "") => _Route({
+	method: "GET",
+	path
+});
+/**
+* Register POST route on the given path (default "") for the given controller.
+*/
+const POST = (path = "") => _Route({
+	method: "POST",
+	path
+});
+/**
+* Register PUT route on the given path (default "") for the given controller.
+*/
+const PUT = (path = "") => _Route({
+	method: "PUT",
+	path
+});
+/**
+* Register DELETE route on the given path (default "") for the given controller.
+*/
+const DELETE = (path = "") => _Route({
+	method: "DELETE",
+	path
+});
+/**
+* Register OPTIONS route on the given path (default "") for the given controller.
+*/
+const OPTIONS = (path = "") => _Route({
+	method: "OPTIONS",
+	path
+});
+/**
+* Register PATCH route on the given path (default "") for the given controller.
+*/
+const PATCH = (path = "") => _Route({
+	method: "PATCH",
+	path
+});
+/**
+* Register HEAD route on the given path (default "") for the given controller.
+*/
+const HEAD = (path = "") => _Route({
+	method: "HEAD",
+	path
+});
+/**
+* Register a middleware route on the given path (default "") for the given controller.
+*/
+const Middleware = (path = "") => _Route({
+	method: "USE",
+	path
+});
+/**
+* Given a class constructor, fetch all the routes attached.
+*/
+function _getRoutes(ctor) {
+	return _routeStore.get(ctor) ?? [];
+}
+//#endregion
+//#region src/annotation/schema.ts
+function ControllerSchema(options) {
+	return (target) => {
+		_setControllerSchema(target, options);
+	};
+}
+function RouteSchema(options) {
+	return (target, propertyKey) => {
+		const ctor = target.constructor;
+		_setRouteSchema(ctor, String(propertyKey), options);
+	};
+}
+const _routeSchemaStore = /* @__PURE__ */ new WeakMap();
+const _controllerSchemaStore = /* @__PURE__ */ new WeakMap();
+function getOrCreateRouteSchemaStore(store, ctor) {
+	const existing = store.get(ctor);
+	if (existing) return existing;
+	const created = /* @__PURE__ */ new Map();
+	store.set(ctor, created);
+	return created;
+}
+function _setRouteSchema(ctor, fnName, options) {
+	getOrCreateRouteSchemaStore(_routeSchemaStore, ctor).set(fnName, options);
+}
+function _setControllerSchema(ctor, options) {
+	_controllerSchemaStore.set(ctor, options);
+}
+function _getRouteSchema(ctor, fnName) {
+	return _routeSchemaStore.get(ctor)?.get(fnName);
+}
+function _getControllerSchema(ctor) {
+	return _controllerSchemaStore.get(ctor);
+}
+//#endregion
+//#region src/annotation/validator.ts
+const _validatorSchemaStore = /* @__PURE__ */ new WeakMap();
+function ResponseBody(schema) {
+	return (target, propertyKey) => {
+		const ctor = target.constructor;
+		const fnName = String(propertyKey);
+		_saveValidatorSchema(_getOrCreateSchemaDefinition(ctor, fnName), "responseBody", schema, fnName);
+	};
+}
+function RequestBody(schema) {
+	return (target, propertyKey) => {
+		const ctor = target.constructor;
+		const fnName = String(propertyKey);
+		_saveValidatorSchema(_getOrCreateSchemaDefinition(ctor, fnName), "requestBody", schema, fnName);
+	};
+}
+function RequestParam(schema) {
+	return (target, propertyKey) => {
+		const ctor = target.constructor;
+		const fnName = String(propertyKey);
+		_saveValidatorSchema(_getOrCreateSchemaDefinition(ctor, fnName), "requestParam", schema, fnName);
+	};
+}
+function RequestQuery(schema) {
+	return (target, propertyKey) => {
+		const ctor = target.constructor;
+		const fnName = String(propertyKey);
+		_saveValidatorSchema(_getOrCreateSchemaDefinition(ctor, fnName), "requestQuery", schema, fnName);
+	};
+}
+function getOrCreateValidatorSchemaStore(store, ctor) {
+	const existing = store.get(ctor);
+	if (existing) return existing;
+	const created = /* @__PURE__ */ new Map();
+	store.set(ctor, created);
+	return created;
+}
+function _getOrCreateSchemaDefinition(ctor, fnName) {
+	const byFn = getOrCreateValidatorSchemaStore(_validatorSchemaStore, ctor);
+	const existing = byFn.get(fnName);
+	if (existing) return existing;
+	const created = {};
+	byFn.set(fnName, created);
+	return created;
+}
+async function _parseOrThrow(schema, input, location, fnName) {
+	const result = await schema["~standard"].validate(input);
+	if (result.issues) throw new ParserError(location, result.issues, schema["~standard"].vendor, fnName);
+	return result.value;
+}
+function _saveValidatorSchema(def, key, schema, fnName) {
+	if (def[key]) throw new Error(`Duplicate schema for "${String(key)}" on method "${fnName}"`);
+	def[key] = schema;
+}
+function _getValidatorSchema(ctor, fnName) {
+	return _validatorSchemaStore.get(ctor)?.get(fnName);
+}
+//#endregion
+//#region src/helper/openapi.ts
+var OpenAPIGenerator = class {
+	OPENAPI_VERSION = "3.0.0";
+	controllers = /* @__PURE__ */ new Set();
+	registerController(controllerClass, prefix) {
+		this.controllers.add({
+			class: controllerClass,
+			prefix
+		});
+	}
+	/**
+	* visible for testing
+	*/
+	_clearControllers() {
+		this.controllers.clear();
+	}
+	get metadata() {
+		return _settings.doc.metadata;
+	}
+	generateSpec() {
+		const metadata = this.metadata;
+		const paths = {};
+		const tags = [];
+		for (const { class: controllerClass, prefix } of this.controllers) {
+			const routes = _getRoutes(controllerClass);
+			const controllerSchema = _getControllerSchema(controllerClass);
+			if (controllerSchema?.title) tags.push({
+				name: controllerSchema.title,
+				description: controllerSchema.description
+			});
+			for (const route of routes) {
+				if (route.method === "USE") continue;
+				const schemas = _getValidatorSchema(controllerClass, route.fnName);
+				const routeSchema = _getRouteSchema(controllerClass, route.fnName);
+				if (route.path instanceof RegExp) throw new Error(`You have a route with a regex path of ${route.path.source}. This is not compatible with OpenAPI.`);
+				const openApiPath = (prefix + route.path).replace(/:([A-Za-z0-9_]+)/g, "{$1}");
+				if (!paths[openApiPath]) paths[openApiPath] = {};
+				const responses = {};
+				if (schemas?.responseBody) {
+					const responseSchema = this.toJsonSchema(schemas.responseBody, "output");
+					responses["200"] = {
+						description: responseSchema.description ?? "Successful response",
+						content: { "application/json": { schema: responseSchema } }
+					};
+				} else responses["200"] = { description: "Successful response" };
+				if (routeSchema?.responses) for (const resp of routeSchema.responses) {
+					const statusCode = String(resp.statusCode);
+					const existingResponse = responses[statusCode];
+					const existingSchema = existingResponse && "content" in existingResponse ? existingResponse.content?.["application/json"]?.schema : void 0;
+					const responseSchema = resp.schema ? this.toJsonSchema(resp.schema, "output") : statusCode === "200" ? existingSchema : void 0;
+					responses[statusCode] = {
+						...existingResponse,
+						description: resp.description ?? responseSchema?.description ?? existingResponse?.description ?? `Response ${resp.statusCode}`,
+						...responseSchema ? { content: { "application/json": { schema: responseSchema } } } : {}
+					};
+				}
+				const operation = {
+					responses,
+					summary: routeSchema?.summary,
+					description: routeSchema?.description,
+					tags: controllerSchema?.title ? [controllerSchema.title] : void 0
+				};
+				const parameters = [];
+				if (schemas?.requestParam) {
+					const paramSchema = this.toJsonSchema(schemas.requestParam, "input");
+					if (paramSchema.type === "object" && paramSchema.properties) for (const [name, schema] of Object.entries(paramSchema.properties)) {
+						const parameterSchema = schema;
+						parameters.push({
+							name,
+							in: "path",
+							required: true,
+							description: parameterSchema.description,
+							schema: parameterSchema
+						});
+					}
+				}
+				if (schemas?.requestQuery) {
+					const querySchema = this.toJsonSchema(schemas.requestQuery, "input");
+					if (querySchema.type === "object" && querySchema.properties) for (const [name, schema] of Object.entries(querySchema.properties)) {
+						const isRequired = Array.isArray(querySchema.required) && querySchema.required.includes(name);
+						const parameterSchema = schema;
+						parameters.push({
+							name,
+							in: "query",
+							required: isRequired,
+							description: parameterSchema.description,
+							schema: parameterSchema
+						});
+					}
+				}
+				if (parameters.length > 0) operation.parameters = parameters;
+				if (schemas?.requestBody) {
+					const requestSchema = this.toJsonSchema(schemas.requestBody, "input");
+					operation.requestBody = {
+						required: true,
+						description: requestSchema.description,
+						content: { "application/json": { schema: requestSchema } }
+					};
+				}
+				const method = route.method.toLowerCase();
+				paths[openApiPath][method] = operation;
+			}
+		}
+		return {
+			openapi: this.OPENAPI_VERSION,
+			info: {
+				title: metadata.title,
+				version: metadata.version,
+				description: metadata.description
+			},
+			tags: tags.length > 0 ? tags : void 0,
+			paths
+		};
+	}
+	toJsonSchema(schema, direction = "output") {
+		try {
+			const jsonSchema = schema["~standard"].jsonSchema;
+			return direction === "input" ? jsonSchema.input({ target: "openapi-3.0" }) : jsonSchema.output({ target: "openapi-3.0" });
+		} catch (e) {
+			if (e instanceof Error && e.message.includes("Transforms cannot be represented in JSON Schema")) throw new Error(`${e.message}.\nIt appears that you are using z.transform() - it is highly recommended that you use z.codec instead - https://zod.dev/codecs`, { cause: e });
+			throw e;
+		}
 	}
 };
+const openApiGenerator = new OpenAPIGenerator();
+function _registerController(controllerClass, prefix) {
+	openApiGenerator.registerController(controllerClass, prefix);
+}
+function generateOpenApiSpec() {
+	return openApiGenerator.generateSpec();
+}
+function _clearOpenApiRegistry() {
+	openApiGenerator._clearControllers();
+}
 //#endregion
 //#region src/types.ts
 const methodResolve = {
@@ -503,214 +894,6 @@ function _resolve(ctor) {
 	return _InjectableRegistry.get(ctor);
 }
 //#endregion
-//#region src/annotation/request.ts
-const _requestSchemaStore = /* @__PURE__ */ new WeakMap();
-/**
-* Apply to a route method to have `request.body` be parsed by `schema`.
-*
-* This annotation will parse `request.body` & then override `request.body`.
-* You can then just simply cast `request.body` for your use
-*
-* @example
-* ```ts
-*  const CREATE_BOOK_REQUEST_BODY_SCHEMA = z.object({
-*    name: z.string(),
-*    description: z.string().optional(),
-*  });
-*
-* ⠀@Controller({ prefix: "/api/book" })
-*  class BookController {
-*   ⠀@RequestBody(CREATE_BOOK_REQUEST_BODY_SCHEMA)
-*   ⠀@POST()
-*    public createBook(request: e.Request) {
-*      const { name, description } = request.body as unknown as z.infer<
-*        typeof CREATE_BOOK_REQUEST_BODY_SCHEMA
-*      >;
-*    }
-*  }
-* ```
-*/
-function RequestBody(schema) {
-	return (target, propertyKey) => {
-		const ctor = target.constructor;
-		const fnName = String(propertyKey);
-		_setOnce(_getOrCreateRequestSchemaDefinition(ctor, fnName), "body", schema, fnName);
-	};
-}
-/**
-* Apply to a route method to have `request.param` be parsed by `schema`.
-*
-* This annotation will parse `request.param` & then override `request.param`.
-* You can then just simply cast `request.param` for your use
-*
-* @example
-* ```ts
-*  const GET_BOOK_REQUEST_PARAM_SCHEMA = z.object({
-*    bookId: z.string(),
-*  });
-*
-* ⠀@Controller({ prefix: "/api/book" })
-*  class BookController {
-*   ⠀@RequestParam(GET_BOOK_REQUEST_PARAM_SCHEMA)
-*   ⠀@GET("/:bookId")
-*    public getBook(request: e.Request) {
-*      const { bookId } = request.param as unknown as z.infer<
-*        typeof GET_BOOK_REQUEST_PARAM_SCHEMA
-*      >;
-*    }
-*  }
-* ```
-*/
-function RequestParam(schema) {
-	return (target, propertyKey) => {
-		const ctor = target.constructor;
-		const fnName = String(propertyKey);
-		_setOnce(_getOrCreateRequestSchemaDefinition(ctor, fnName), "param", schema, fnName);
-	};
-}
-/**
-* Apply to a route method to have `request.query` be parsed by `schema`.
-*
-* This annotation will parse `request.query` & then override `request.query`.
-* You can then just simply cast `request.query` for your use
-*
-* @example
-* ```ts
-*  const LIST_BOOKS_REQUEST_QUERY_SCHEMA = z.object({
-*    sort: z.enum(["name", "createdAt"]).optional(),
-*    q: z.string().optional(),
-*  });
-*
-* ⠀@Controller({ prefix: "/api/book" })
-*  class BookController {
-*   ⠀@RequestQuery(LIST_BOOKS_REQUEST_QUERY_SCHEMA)
-*   ⠀@GET()
-*    public listBooks(request: e.Request) {
-*      const { sort, q } = request.query as unknown as z.infer<
-*        typeof LIST_BOOKS_REQUEST_QUERY_SCHEMA
-*      >;
-*    }
-*  }
-* ```
-*/
-function RequestQuery(schema) {
-	return (target, propertyKey) => {
-		const ctor = target.constructor;
-		const fnName = String(propertyKey);
-		_setOnce(_getOrCreateRequestSchemaDefinition(ctor, fnName), "query", schema, fnName);
-	};
-}
-function _getOrCreateRequestSchemaDefinition(ctor, fnName) {
-	const byFn = (() => {
-		const fn = _requestSchemaStore.get(ctor);
-		if (fn) return fn;
-		const newFn = /* @__PURE__ */ new Map();
-		_requestSchemaStore.set(ctor, newFn);
-		return newFn;
-	})();
-	const existing = byFn.get(fnName);
-	if (existing) return existing;
-	const created = {};
-	byFn.set(fnName, created);
-	return created;
-}
-function _setOnce(def, key, schema, fnName) {
-	if (def[key]) throw new Error(`Duplicate request schema for "${String(key)}" on method "${fnName}"`);
-	def[key] = schema;
-}
-function _getRequestSchemas(ctor, fnName) {
-	return _requestSchemaStore.get(ctor)?.get(fnName);
-}
-async function _parseOrThrow(schema, input, kind) {
-	const result = await schema["~standard"].validate(input);
-	if (result.issues) {
-		console.debug(`Failed to parse a schema`);
-		throw new ParserError(kind, result.issues, schema["~standard"].vendor);
-	}
-	return result.value;
-}
-//#endregion
-//#region src/annotation/route.ts
-const _routeStore = /* @__PURE__ */ new WeakMap();
-/**
-* Custom annotation that will store all routes inside of a map,
-* which can then be used to initialize all the routes to the router.
-*/
-function _Route({ method, path = "" }) {
-	return (target, propertyKey) => {
-		const ctor = target.constructor;
-		const list = _routeStore.get(ctor) ?? [];
-		list.push({
-			method,
-			path: path ?? "",
-			fnName: String(propertyKey)
-		});
-		_routeStore.set(ctor, list);
-	};
-}
-/**
-* Register GET route on the given path (default "") for the given controller.
-*/
-const GET = (path = "") => _Route({
-	method: "GET",
-	path
-});
-/**
-* Register POST route on the given path (default "") for the given controller.
-*/
-const POST = (path = "") => _Route({
-	method: "POST",
-	path
-});
-/**
-* Register PUT route on the given path (default "") for the given controller.
-*/
-const PUT = (path = "") => _Route({
-	method: "PUT",
-	path
-});
-/**
-* Register DELETE route on the given path (default "") for the given controller.
-*/
-const DELETE = (path = "") => _Route({
-	method: "DELETE",
-	path
-});
-/**
-* Register OPTIONS route on the given path (default "") for the given controller.
-*/
-const OPTIONS = (path = "") => _Route({
-	method: "OPTIONS",
-	path
-});
-/**
-* Register PATCH route on the given path (default "") for the given controller.
-*/
-const PATCH = (path = "") => _Route({
-	method: "PATCH",
-	path
-});
-/**
-* Register HEAD route on the given path (default "") for the given controller.
-*/
-const HEAD = (path = "") => _Route({
-	method: "HEAD",
-	path
-});
-/**
-* Register a middleware route on the given path (default "") for the given controller.
-*/
-const Middleware = (path = "") => _Route({
-	method: "USE",
-	path
-});
-/**
-* Given a class constructor, fetch all the routes attached.
-*/
-function _getRoutes(ctor) {
-	return _routeStore.get(ctor) ?? [];
-}
-//#endregion
 //#region src/annotation/controller.ts
 const _ControllerRegistry = /* @__PURE__ */ new WeakMap();
 /**
@@ -722,6 +905,7 @@ const _ControllerRegistry = /* @__PURE__ */ new WeakMap();
 function Controller({ prefix = "", deps = [] } = {}) {
 	return (target) => {
 		const targetClass = target;
+		_registerController(target, prefix);
 		const router = (0, express.Router)();
 		const routes = _getRoutes(target);
 		const usedRoutes = /* @__PURE__ */ new Set();
@@ -746,15 +930,20 @@ Split these into separate @MiddlewareClass classes, or merge the logic into a si
 			if (method === "USE" && fn.length >= 4) {
 				const middlewareFn = async (err, request, response, next) => {
 					try {
-						const result = fn.bind(controllerInstance)(err, request, response, next);
-						if (result instanceof ResponseEntity) {
-							response.contentType("application/json").status(result.getStatusCode()).set(result.getHeaders()).send(Sapling.serialize(result.getBody()));
-							return;
-						}
-						if (result instanceof RedirectView) {
-							response.redirect(result.getUrl());
-							return;
-						}
+						await validate({
+							target,
+							fnName,
+							request
+						});
+						await handleResult({
+							result: fn.bind(controllerInstance)(err, request, response, next),
+							response,
+							target,
+							fnName,
+							method,
+							path: path instanceof RegExp ? path.source : fp,
+							isErrorMiddleware: true
+						});
 					} catch (e) {
 						console.error(e);
 						next(e);
@@ -764,34 +953,52 @@ Split these into separate @MiddlewareClass classes, or merge the logic into a si
 				return;
 			}
 			router[methodName](fp, async (request, response, next) => {
-				const schemas = _getRequestSchemas(target, fnName);
-				if (schemas) {
-					if (schemas.body) request.body = await _parseOrThrow(schemas.body, request.body, "reqbody");
-					if (schemas.param) request.params = await _parseOrThrow(schemas.param, request.params, "reqparams");
-					if (schemas.query) {
-						const parsedQuery = await _parseOrThrow(schemas.query, request.query, "reqquery");
-						Object.defineProperty(request, "query", {
-							value: parsedQuery,
-							writable: true,
-							configurable: true
-						});
-					}
-				}
-				const result = await fn.bind(controllerInstance)(request, response, next);
-				if (result instanceof ResponseEntity) {
-					response.contentType("application/json").status(result.getStatusCode()).set(result.getHeaders()).send(Sapling.serialize(result.getBody()));
-					return;
-				}
-				if (result instanceof RedirectView) {
-					response.redirect(result.getUrl());
-					return;
-				}
-				if (method !== "USE" && !response.writableEnded) response.status(404).send(Html404ErrorPage(`Cannot ${methodName.toUpperCase()} ${path instanceof RegExp ? path.source : fp}`));
+				await validate({
+					target,
+					fnName,
+					request
+				});
+				await handleResult({
+					result: await fn.bind(controllerInstance)(request, response, next),
+					response,
+					target,
+					fnName,
+					method,
+					path: path instanceof RegExp ? path.source : fp
+				});
 			});
 		}
 		_ControllerRegistry.set(targetClass, router);
 	};
 }
+async function handleResult({ result, target, fnName, response, method, path, isErrorMiddleware = false }) {
+	const schemas = _getValidatorSchema(target, fnName);
+	if (result instanceof ResponseEntity) {
+		const body = schemas && schemas.responseBody ? await _parseOrThrow(schemas.responseBody, result.getBody(), "resbody", fnName) : result.getBody();
+		response.contentType("application/json").status(result.getStatusCode()).set(result.getHeaders()).send(Sapling.serialize(body));
+		return;
+	}
+	if (result instanceof RedirectView) {
+		response.redirect(result.getUrl());
+		return;
+	}
+	if (!isErrorMiddleware && method !== "USE" && !response.writableEnded) response.status(404).send(Html404ErrorPage(`Cannot ${method} ${path}`));
+}
+async function validate({ target, fnName, request }) {
+	const schemas = _getValidatorSchema(target, fnName);
+	if (schemas) {
+		if (schemas.requestBody) request.body = await _parseOrThrow(schemas.requestBody, request.body, "reqbody", fnName);
+		if (schemas.requestParam) request.params = await _parseOrThrow(schemas.requestParam, request.params, "reqparams", fnName);
+		if (schemas.requestQuery) {
+			const parsedQuery = await _parseOrThrow(schemas.requestQuery, request.query, "reqquery", fnName);
+			Object.defineProperty(request, "query", {
+				value: parsedQuery,
+				writable: true,
+				configurable: true
+			});
+		}
+	}
+}
 //#endregion
 //#region src/annotation/middleware.ts
 /**
@@ -813,7 +1020,7 @@ function __decorate(decorators, target, key, desc) {
 	return c > 3 && r && Object.defineProperty(target, key, r), r;
 }
 //#endregion
-//#region src/middleware/default/base.ts
+//#region src/middleware/default/error/base.ts
 let DefaultBaseErrorMiddleware = class DefaultBaseErrorMiddleware {
 	handle(err, _request, _response, _next) {
 		console.error("[Error]", err);
@@ -823,7 +1030,20 @@ let DefaultBaseErrorMiddleware = class DefaultBaseErrorMiddleware {
 __decorate([Middleware()], DefaultBaseErrorMiddleware.prototype, "handle", null);
 DefaultBaseErrorMiddleware = __decorate([MiddlewareClass()], DefaultBaseErrorMiddleware);
 //#endregion
-//#region src/middleware/default/responsestatus.ts
+//#region src/middleware/default/error/parse.ts
+let DefaultParserErrorMiddleware = class DefaultParserErrorMiddleware {
+	handle(err, _request, _response, next) {
+		if (err instanceof ParserError) {
+			console.warn(err);
+			return ResponseEntity.status(err.status).body({ message: err.message });
+		}
+		next(err);
+	}
+};
+__decorate([Middleware()], DefaultParserErrorMiddleware.prototype, "handle", null);
+DefaultParserErrorMiddleware = __decorate([MiddlewareClass()], DefaultParserErrorMiddleware);
+//#endregion
+//#region src/middleware/default/error/responsestatus.ts
 let DefaultResponseStatusErrorMiddleware = class DefaultResponseStatusErrorMiddleware {
 	handle(err, _request, _response, next) {
 		if (err instanceof ResponseStatusError) return ResponseEntity.status(err.status).body({ message: err.message });
@@ -833,7 +1053,90 @@ let DefaultResponseStatusErrorMiddleware = class DefaultResponseStatusErrorMiddl
 __decorate([Middleware()], DefaultResponseStatusErrorMiddleware.prototype, "handle", null);
 DefaultResponseStatusErrorMiddleware = __decorate([MiddlewareClass()], DefaultResponseStatusErrorMiddleware);
 //#endregion
+//#region src/middleware/default/openapi/index.ts
+let DefaultOpenApiMiddleware = class DefaultOpenApiMiddleware {
+	handle(_request, _response, _next) {
+		return ResponseEntity.ok().body(generateOpenApiSpec());
+	}
+};
+__decorate([GET(_settings.doc.openApiPath)], DefaultOpenApiMiddleware.prototype, "handle", null);
+DefaultOpenApiMiddleware = __decorate([MiddlewareClass()], DefaultOpenApiMiddleware);
+//#endregion
+//#region src/middleware/default/swagger/index.ts
+/**
+* Enable the serving of the Swagger endpoint used to serve the OpenAPI spec generated by Sapling.
+*
+* Configure any middleware-specific settings with `Sapling.Extras.swaggerAndOpenApi`
+*
+* You must register `DefaultSwaggerMiddleware.Serve` & `DefaultSwaggerMiddleware.Setup` after `DefaultOpenApiMiddleware`
+*
+* ```ts
+*  const middlewares = [
+*    DefaultOpenApiMiddleware,
+*    DefaultSwaggerMiddleware.Serve,
+*    DefaultSwaggerMiddleware.Setup,
+*  ];
+*  middlewares.map(Sapling.resolve).forEach((r) => app.use(r));
+* ```
+*/
+let Serve = class Serve {
+	handlers = swagger_ui_express.default.serve;
+	handle(request, response, next) {
+		return Sapling.chainHandlers(this.handlers, request, response, next);
+	}
+};
+__decorate([Middleware(_settings.doc.swaggerPath)], Serve.prototype, "handle", null);
+Serve = __decorate([MiddlewareClass()], Serve);
+/**
+* Enable the serving of the Swagger endpoint used to serve the OpenAPI spec generated by Sapling.
+*
+* Configure any middleware-specific settings with `Sapling.Extras.swaggerAndOpenApi`
+*
+* You must register `DefaultSwaggerMiddleware.Serve` & `DefaultSwaggerMiddleware.Setup` after `DefaultOpenApiMiddleware`
+*
+* ```ts
+*  const middlewares = [
+*    DefaultOpenApiMiddleware,
+*    DefaultSwaggerMiddleware.Serve,
+*    DefaultSwaggerMiddleware.Setup,
+*  ];
+*  middlewares.map(Sapling.resolve).forEach((r) => app.use(r));
+* ```
+*/
+let Setup = class Setup {
+	handler;
+	constructor() {
+		this.handler = swagger_ui_express.default.setup(null, { swaggerOptions: { url: _settings.doc.openApiPath } });
+	}
+	handle(request, response, next) {
+		return this.handler(request, response, next);
+	}
+};
+__decorate([Middleware(_settings.doc.swaggerPath)], Setup.prototype, "handle", null);
+Setup = __decorate([MiddlewareClass()], Setup);
+/**
+* Enable the serving of the Swagger endpoint used to serve the OpenAPI spec generated by Sapling.
+*
+* Configure any middleware-specific settings with `Sapling.Extras.swaggerAndOpenApi`
+*
+* You must register `DefaultSwaggerMiddleware.Serve` & `DefaultSwaggerMiddleware.Setup` after `DefaultOpenApiMiddleware`
+*
+* ```ts
+*  const middlewares = [
+*    DefaultOpenApiMiddleware,
+*    DefaultSwaggerMiddleware.Serve,
+*    DefaultSwaggerMiddleware.Setup,
+*  ];
+*  middlewares.map(Sapling.resolve).forEach((r) => app.use(r));
+* ```
+*/
+const DefaultSwaggerMiddleware = {
+	Serve,
+	Setup
+};
+//#endregion
 exports.Controller = Controller;
+exports.ControllerSchema = ControllerSchema;
 exports.DELETE = DELETE;
 Object.defineProperty(exports, "DefaultBaseErrorMiddleware", {
 	enumerable: true,
@@ -841,12 +1144,25 @@ Object.defineProperty(exports, "DefaultBaseErrorMiddleware", {
 		return DefaultBaseErrorMiddleware;
 	}
 });
+Object.defineProperty(exports, "DefaultOpenApiMiddleware", {
+	enumerable: true,
+	get: function() {
+		return DefaultOpenApiMiddleware;
+	}
+});
+Object.defineProperty(exports, "DefaultParserErrorMiddleware", {
+	enumerable: true,
+	get: function() {
+		return DefaultParserErrorMiddleware;
+	}
+});
 Object.defineProperty(exports, "DefaultResponseStatusErrorMiddleware", {
 	enumerable: true,
 	get: function() {
 		return DefaultResponseStatusErrorMiddleware;
 	}
 });
+exports.DefaultSwaggerMiddleware = DefaultSwaggerMiddleware;
 exports.GET = GET;
 exports.HEAD = HEAD;
 exports.Html404ErrorPage = Html404ErrorPage;
@@ -863,16 +1179,29 @@ exports.RedirectView = RedirectView;
 exports.RequestBody = RequestBody;
 exports.RequestParam = RequestParam;
 exports.RequestQuery = RequestQuery;
+exports.ResponseBody = ResponseBody;
 exports.ResponseEntity = ResponseEntity;
 exports.ResponseEntityBuilder = ResponseEntityBuilder;
 exports.ResponseStatusError = ResponseStatusError;
+exports.RouteSchema = RouteSchema;
 exports.Sapling = Sapling;
 exports._ControllerRegistry = _ControllerRegistry;
 exports._InjectableDeps = _InjectableDeps;
 exports._InjectableRegistry = _InjectableRegistry;
 exports._Route = _Route;
-exports._getRequestSchemas = _getRequestSchemas;
+exports._clearOpenApiRegistry = _clearOpenApiRegistry;
+exports._getControllerSchema = _getControllerSchema;
+exports._getOrCreateSchemaDefinition = _getOrCreateSchemaDefinition;
+exports._getRouteSchema = _getRouteSchema;
 exports._getRoutes = _getRoutes;
+exports._getValidatorSchema = _getValidatorSchema;
 exports._parseOrThrow = _parseOrThrow;
+exports._registerController = _registerController;
 exports._resolve = _resolve;
+exports._saveValidatorSchema = _saveValidatorSchema;
+exports._setControllerSchema = _setControllerSchema;
+exports._setRouteSchema = _setRouteSchema;
+exports._settings = _settings;
+exports.generateOpenApiSpec = generateOpenApiSpec;
 exports.methodResolve = methodResolve;
+exports.openApiGenerator = openApiGenerator;