npm - @tahminator/sapling - Versions diffs - 2.0.5-beta.c70dc62b → 2.0.5-beta.e0403942 - Mend

@tahminator/sapling 2.0.5-beta.c70dc62b → 2.0.5-beta.e0403942

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.mjs CHANGED Viewed

@@ -23,6 +23,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;
 	}
@@ -118,8 +119,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;
@@ -172,8 +175,9 @@ var ResponseEntity = class {
 * ensuring type safety when constructing the response.
 */
 var ResponseEntityBuilder = class {
+	_statusCode;
+	_headers = {};
 	constructor(statusCode) {
-		this._headers = {};
 		this._statusCode = statusCode;
 	}
 	/**
@@ -205,6 +209,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;
@@ -216,26 +221,27 @@ 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";
-				case "resbody": return "response body";
-			}
-		})()}: ${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
@@ -245,7 +251,11 @@ const _settings = {
 	deserialize: JSON.parse,
 	doc: {
 		openApiPath: "/openapi.json",
-		swaggerPath: "/swagger.html"
+		swaggerPath: "/swagger.html",
+		metadata: {
+			title: "API",
+			version: "1.0.0"
+		}
 	}
 };
 /**
@@ -351,12 +361,59 @@ var Sapling = class Sapling {
 	static setDeserializeFn(fn) {
 		_settings.deserialize = fn;
 	}
-	static setOpenApiPath(path) {
-		_settings.doc.openApiPath = path;
-	}
-	static setSwaggerPath(path) {
-		_settings.doc.swaggerPath = path;
-	}
+	/**
+	* 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();
@@ -453,18 +510,33 @@ function _getRoutes(ctor) {
 	return _routeStore.get(ctor) ?? [];
 }
 //#endregion
-//#region src/utils.ts
-function _getOrCreateMap(store, ctor) {
+//#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;
 }
-//#endregion
-//#region src/annotation/schema.ts
-const _routeSchemaStore = /* @__PURE__ */ new WeakMap();
-const _controllerSchemaStore = /* @__PURE__ */ new WeakMap();
+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);
 }
@@ -472,26 +544,78 @@ 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 {
-	constructor() {
-		this.controllers = /* @__PURE__ */ new Set();
-		this.config = {
-			title: "API",
-			version: "1.0.0"
-		};
-	}
-	setConfig(config) {
-		this.config = config;
-	}
+	controllers = /* @__PURE__ */ new Set();
 	registerController(controllerClass, prefix) {
 		this.controllers.add({
 			class: controllerClass,
 			prefix
 		});
 	}
+	get metadata() {
+		return _settings.doc.metadata;
+	}
 	generateSpec() {
-		const config = this.config;
+		const metadata = this.metadata;
 		const paths = {};
 		const tags = [];
 		for (const { class: controllerClass, prefix } of this.controllers) {
@@ -506,50 +630,70 @@ var OpenAPIGenerator = class {
 				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;
+				const openApiPath = (prefix + route.path).replace(/:([A-Za-z0-9_]+)/g, "{$1}");
 				if (!paths[openApiPath]) paths[openApiPath] = {};
 				const responses = {};
-				if (schemas?.responseBody) responses["200"] = {
-					description: "Successful response",
-					content: { "application/json": { schema: this.toJsonSchema(schemas.responseBody) } }
-				};
-				else responses["200"] = { description: "Successful response" };
-				if (routeSchema?.responses) for (const resp of routeSchema.responses) responses[String(resp.statusCode)] = {
-					description: `Response ${resp.statusCode}`,
-					content: { "application/json": { schema: this.toJsonSchema(resp.schema) } }
-				};
+				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);
-					if (paramSchema.type === "object" && paramSchema.properties) for (const [name, schema] of Object.entries(paramSchema.properties)) parameters.push({
-						name,
-						in: "path",
-						required: true,
-						schema
-					});
+					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);
+					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,
-							schema
+							description: parameterSchema.description,
+							schema: parameterSchema
 						});
 					}
 				}
 				if (parameters.length > 0) operation.parameters = parameters;
-				if (schemas?.requestBody) operation.requestBody = {
-					required: true,
-					content: { "application/json": { schema: this.toJsonSchema(schemas.requestBody) } }
-				};
+				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;
 			}
@@ -557,30 +701,28 @@ var OpenAPIGenerator = class {
 		return {
 			openapi: "3.0.0",
 			info: {
-				title: config.title,
-				version: config.version,
-				description: config.description
+				title: metadata.title,
+				version: metadata.version,
+				description: metadata.description
 			},
 			tags: tags.length > 0 ? tags : void 0,
 			paths
 		};
 	}
-	toJsonSchema(schema) {
+	toJsonSchema(schema, direction = "output") {
 		try {
-			return schema["~standard"].jsonSchema.output({ target: "openapi-3.0" });
+			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`);
+			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 _registerControllerClass(controllerClass, prefix) {
+function _registerController(controllerClass, prefix) {
 	openApiGenerator.registerController(controllerClass, prefix);
 }
-function setOpenApiConfig(config) {
-	openApiGenerator.setConfig(config);
-}
 function generateOpenApiSpec() {
 	return openApiGenerator.generateSpec();
 }
@@ -717,60 +859,6 @@ function _resolve(ctor) {
 	return _InjectableRegistry.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);
-		_setOnce(_getOrCreateSchemaDefinition(ctor, fnName), "responseBody", schema, fnName);
-	};
-}
-function RequestBody(schema) {
-	return (target, propertyKey) => {
-		const ctor = target.constructor;
-		const fnName = String(propertyKey);
-		_setOnce(_getOrCreateSchemaDefinition(ctor, fnName), "requestBody", schema, fnName);
-	};
-}
-function RequestParam(schema) {
-	return (target, propertyKey) => {
-		const ctor = target.constructor;
-		const fnName = String(propertyKey);
-		_setOnce(_getOrCreateSchemaDefinition(ctor, fnName), "requestParam", schema, fnName);
-	};
-}
-function RequestQuery(schema) {
-	return (target, propertyKey) => {
-		const ctor = target.constructor;
-		const fnName = String(propertyKey);
-		_setOnce(_getOrCreateSchemaDefinition(ctor, fnName), "requestQuery", schema, fnName);
-	};
-}
-function _getOrCreateSchemaDefinition(ctor, fnName) {
-	const byFn = _getOrCreateMap(_validatorSchemaStore, ctor);
-	const existing = byFn.get(fnName);
-	if (existing) return existing;
-	const created = {};
-	byFn.set(fnName, created);
-	return created;
-}
-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;
-}
-function _getValidatorSchema(ctor, fnName) {
-	return _validatorSchemaStore.get(ctor)?.get(fnName);
-}
-function _setOnce(def, key, schema, fnName) {
-	if (def[key]) throw new Error(`Duplicate schema for "${String(key)}" on method "${fnName}"`);
-	def[key] = schema;
-}
-//#endregion
 //#region src/annotation/controller.ts
 const _ControllerRegistry = /* @__PURE__ */ new WeakMap();
 /**
@@ -782,7 +870,7 @@ const _ControllerRegistry = /* @__PURE__ */ new WeakMap();
 function Controller({ prefix = "", deps = [] } = {}) {
 	return (target) => {
 		const targetClass = target;
-		_registerControllerClass(target, prefix);
+		_registerController(target, prefix);
 		const router = Router();
 		const routes = _getRoutes(target);
 		const usedRoutes = /* @__PURE__ */ new Set();
@@ -807,15 +895,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);
@@ -825,35 +918,52 @@ Split these into separate @MiddlewareClass classes, or merge the logic into a si
 				return;
 			}
 			router[methodName](fp, async (request, response, next) => {
-				const schemas = _getValidatorSchema(target, fnName);
-				if (schemas) {
-					if (schemas.requestBody) request.body = await _parseOrThrow(schemas.requestBody, request.body, "reqbody");
-					if (schemas.requestParam) request.params = await _parseOrThrow(schemas.requestParam, request.params, "reqparams");
-					if (schemas.requestQuery) {
-						const parsedQuery = await _parseOrThrow(schemas.requestQuery, 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) {
-					const body = schemas && schemas.responseBody ? await _parseOrThrow(schemas.responseBody, result.getBody(), "resbody") : 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 (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
 /**
@@ -888,7 +998,10 @@ DefaultBaseErrorMiddleware = __decorate([MiddlewareClass()], DefaultBaseErrorMid
 //#region src/middleware/default/error/parse.ts
 let DefaultParserErrorMiddleware = class DefaultParserErrorMiddleware {
 	handle(err, _request, _response, next) {
-		if (err instanceof ParserError) return ResponseEntity.status(err.status).body({ message: err.message });
+		if (err instanceof ParserError) {
+			console.warn(err);
+			return ResponseEntity.status(err.status).body({ message: err.message });
+		}
 		next(err);
 	}
 };
@@ -915,17 +1028,48 @@ __decorate([GET(_settings.doc.openApiPath)], DefaultOpenApiMiddleware.prototype,
 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 {
-	constructor() {
-		this.handlers = swagger.serve;
-	}
+	handlers = swagger.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.setup(null, { swaggerOptions: { url: _settings.doc.openApiPath } });
 	}
@@ -935,9 +1079,25 @@ let Setup = class Setup {
 };
 __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
-export { Controller, DELETE, DefaultBaseErrorMiddleware, DefaultOpenApiMiddleware, DefaultParserErrorMiddleware, DefaultResponseStatusErrorMiddleware, DefaultSwaggerMiddleware, GET, HEAD, Html404ErrorPage, HttpStatus, Injectable, Middleware, MiddlewareClass, OPTIONS, PATCH, POST, PUT, ParserError, RedirectView, RequestBody, RequestParam, RequestQuery, ResponseBody, ResponseEntity, ResponseEntityBuilder, ResponseStatusError, Sapling, _ControllerRegistry, _InjectableDeps, _InjectableRegistry, _Route, _getOrCreateSchemaDefinition, _getRoutes, _getValidatorSchema, _parseOrThrow, _registerControllerClass, _resolve, _setOnce, _settings, generateOpenApiSpec, methodResolve, openApiGenerator, setOpenApiConfig };
+export { Controller, ControllerSchema, DELETE, DefaultBaseErrorMiddleware, DefaultOpenApiMiddleware, DefaultParserErrorMiddleware, DefaultResponseStatusErrorMiddleware, DefaultSwaggerMiddleware, GET, HEAD, Html404ErrorPage, HttpStatus, Injectable, Middleware, MiddlewareClass, OPTIONS, PATCH, POST, PUT, ParserError, RedirectView, RequestBody, RequestParam, RequestQuery, ResponseBody, ResponseEntity, ResponseEntityBuilder, ResponseStatusError, RouteSchema, Sapling, _ControllerRegistry, _InjectableDeps, _InjectableRegistry, _Route, _getControllerSchema, _getOrCreateSchemaDefinition, _getRouteSchema, _getRoutes, _getValidatorSchema, _parseOrThrow, _registerController, _resolve, _saveValidatorSchema, _setControllerSchema, _setRouteSchema, _settings, generateOpenApiSpec, methodResolve, openApiGenerator };