moonflower 1.2.0 → 1.3.1

package/src/hooks/useRequestBody.ts

@@ -1,14 +1,20 @@
 import { ParameterizedContext } from 'koa'
+import z from 'zod'
 
 import { ValidationError } from '../errors/UserFacingErrors'
 import { keysOf } from '../utils/object'
-import { getMissingParamMessage, getValidationResultMessage } from '../utils/validationMessages'
+import { getValidationResultMessage } from '../utils/validationMessages'
 import { Validator } from '../validators/types'
+import { validateMissingParams } from '../validators/validateMissingParams'
+import { validateParam } from '../validators/validateParam'
 
 type CheckIfOptional<T, B extends boolean | undefined> = B extends false ? T : T | undefined
 
-type ValidatedData<T extends Record<string, Validator<any>>> = {
-	[K in keyof T]: CheckIfOptional<ReturnType<T[K]['parse']>, T[K]['optional']>
+type ValidatedData<T extends Record<string, Validator<any> | z.ZodType<any>>> = {
+	[K in keyof T]: CheckIfOptional<
+		ReturnType<T[K] extends Validator<any> ? T[K]['parse'] : T[K]['parse']>,
+		T[K] extends Validator<any> ? T[K]['optional'] : false
+	>
 }
 
 /**
@@ -22,7 +28,7 @@ type ValidatedData<T extends Record<string, Validator<any>>> = {
  * @param validators Validator definitions
  * @returns Validated parameters
  */
-export const useRequestBody = <ValidatorsT extends Record<string, Validator<any>>>(
+export const useRequestBody = <ValidatorsT extends Record<string, Validator<any> | z.ZodType<any>>>(
 	ctx: ParameterizedContext,
 	validators: ValidatorsT,
 ): ValidatedData<ValidatorsT> => {
@@ -32,44 +38,19 @@ export const useRequestBody = <ValidatorsT extends Record<string, Validator<any>
 		validator: validators[name],
 	}))
 
-	const missingParams = params.filter(
-		(param) => providedParams[param.name] === undefined && !validators[param.name].optional,
-	)
-
-	if (missingParams.length > 0) {
-		throw new ValidationError(
-			`Missing body params: ${missingParams.map((param) => getMissingParamMessage(param)).join(', ')}`,
-		)
-	}
+	validateMissingParams(params, providedParams, validators, 'body')
 
 	const validationResults = params.map((param) => {
 		const paramValue = providedParams[param.name]
 
 		// Param is optional and is not provided - skip validation
 		if (paramValue === undefined) {
-			return { param, validated: true }
+			return { param, validated: true, parsedValue: undefined, exception: null }
 		}
 
-		try {
-			const convertedValue = (() => {
-				if (paramValue === null) {
-					return null
-				} else if (typeof paramValue === 'object') {
-					return JSON.stringify(paramValue)
-				}
-				return String(paramValue)
-			})()
-			const validatorObject = param.validator
-			const prevalidatorSuccess = !validatorObject.prevalidate || validatorObject.prevalidate(convertedValue)
-			const parsedValue = validatorObject.parse(convertedValue)
-			const validatorSuccess = !validatorObject.validate || validatorObject.validate(parsedValue)
-			return {
-				param,
-				validated: prevalidatorSuccess && validatorSuccess,
-				parsedValue,
-			}
-		} catch {
-			return { param, validated: false }
+		return {
+			...validateParam(param.validator, paramValue),
+			param,
 		}
 	})
 
@@ -78,7 +59,7 @@ export const useRequestBody = <ValidatorsT extends Record<string, Validator<any>
 	if (failedValidations.length > 0) {
 		throw new ValidationError(
 			`Failed body param validation: ${failedValidations
-				.map((result) => getValidationResultMessage(result.param))
+				.map((result) => getValidationResultMessage(result.param, result.exception))
 				.join(', ')}`,
 		)
 	}

package/src/openapi/analyzerModule/analyzerModule.ts

@@ -12,7 +12,7 @@ import { discoverRouters } from '../discoveryModule/discoverRouters/discoverRout
 import { ApiDocsHeader, OpenApiManager } from '../manager/OpenApiManager'
 import { EndpointData, ExposedModelData } from '../types'
 import { getSourceFileTimestamp, TimestampCache } from './getSourceFileTimestamp'
-import { getValuesOfObjectLiteral } from './nodeParsers'
+import { getValuesOfObjectLiteral, resolveEndpointPath } from './nodeParsers'
 import { parseEndpoint } from './parseEndpoint'
 import { parseExposedModel, parseNamedExposedModels } from './parseExposedModels'
 import { SourceFileCache } from './sourceFileCache'
@@ -214,8 +214,7 @@ export const analyzeSourceFileEndpoints = (
 			const routerPattern = new RegExp(`${routerName}\\.(?:${joinedOperations})`)
 
 			if (routerPattern.test(nodeText)) {
-				const endpointText = node.getFirstDescendantByKind(SyntaxKind.StringLiteral)?.getText() ?? ''
-				const endpointPath = endpointText.slice(1, -1)
+				const endpointPath = resolveEndpointPath(node) ?? ''
 
 				if (filterEndpointPaths && !filterEndpointPaths.some((path) => endpointPath.includes(path))) {
 					return

package/src/openapi/analyzerModule/nodeParsers.ts

@@ -253,7 +253,87 @@ export const getShapeOfValidatorLiteral = (
 	return properties || []
 }
 
+const isZodCallExpression = (node: Node): boolean => {
+	const callExpression = node.asKind(SyntaxKind.CallExpression)
+	if (!callExpression) {
+		return false
+	}
+	const returnType = callExpression.getReturnType()
+	const typeName = returnType.getSymbol()?.getName() ?? ''
+	return typeName.startsWith('Zod')
+}
+
+const getZodCallShape = (node: Node): ShapeOfType['shape'] => {
+	const callExpression = node.asKind(SyntaxKind.CallExpression)!
+	const returnType = callExpression.getReturnType()
+	const typeName = returnType.getSymbol()?.getName() ?? ''
+
+	if (typeName === 'ZodNumber') {
+		return 'number'
+	}
+	if (typeName === 'ZodString') {
+		return 'string'
+	}
+	if (typeName === 'ZodBoolean') {
+		return 'boolean'
+	}
+	if (typeName === 'ZodBigInt') {
+		return 'bigint'
+	}
+
+	if (typeName === 'ZodObject') {
+		const argNode = callExpression.getFirstChildByKind(SyntaxKind.SyntaxList)?.getFirstChild()
+		const objectLiteral = argNode?.asKind(SyntaxKind.ObjectLiteralExpression)
+		if (!objectLiteral) {
+			return 'unknown_zod_object'
+		}
+		const syntaxList = objectLiteral.getFirstChildByKind(SyntaxKind.SyntaxList)
+		if (!syntaxList) {
+			return []
+		}
+		const properties = syntaxList.getChildrenOfKind(SyntaxKind.PropertyAssignment)
+		return properties.map((prop) => {
+			const identifier = prop.getFirstChildByKind(SyntaxKind.Identifier)!.getText()
+			const valueNode = prop.getLastChild()!
+			return {
+				role: 'property' as const,
+				identifier,
+				shape: isZodCallExpression(valueNode)
+					? getZodCallShape(valueNode)
+					: getValidatorPropertyShape(valueNode),
+				optional: false,
+			}
+		})
+	}
+
+	if (typeName === 'ZodArray') {
+		const argNode = callExpression.getFirstChildByKind(SyntaxKind.SyntaxList)?.getFirstChild()
+		if (!argNode) {
+			return 'unknown_zod_array'
+		}
+		const elementShape = isZodCallExpression(argNode)
+			? getZodCallShape(argNode)
+			: getValidatorPropertyShape(argNode)
+		return [
+			{
+				role: 'array' as const,
+				shape: elementShape,
+				optional: false,
+			},
+		]
+	}
+
+	const fileName = node.getSourceFile().getFilePath().split('/').pop()
+	Logger.warn(`[${fileName}] Unknown zod type: ${typeName}`)
+	return 'unknown_zod'
+}
+
 export const getValidatorPropertyShape = (innerLiteralNode: Node): ShapeOfType['shape'] => {
+	// Zod validator (e.g. z.number(), z.string(), z.object({...}), z.array(...))
+	if (isZodCallExpression(innerLiteralNode)) {
+		return getZodCallShape(innerLiteralNode)
+	}
+
 	// Inline definition with `as Validator<...>` clause
 	const inlineValidatorAsExpression = innerLiteralNode
 		.getParent()!
@@ -360,6 +440,10 @@ export const getValidatorPropertyShape = (innerLiteralNode: Node): ShapeOfType['
 }
 
 export const getValidatorPropertyOptionality = (node: Node): boolean => {
+	if (isZodCallExpression(node)) {
+		return false
+	}
+
 	const callExpressionNode = node.asKind(SyntaxKind.CallExpression)
 	if (callExpressionNode) {
 		const identifierNode = callExpressionNode.getFirstChildByKind(SyntaxKind.Identifier)
@@ -393,6 +477,10 @@ export const getValidatorPropertyStringValue = (
 	nodeOrReference: Node,
 	name: 'description' | 'errorMessage',
 ): string => {
+	if (isZodCallExpression(nodeOrReference)) {
+		return ''
+	}
+
 	const node = findNodeImplementation(nodeOrReference)
 
 	const callExpressionNode = node.asKind(SyntaxKind.CallExpression)
@@ -571,14 +659,16 @@ export const getProperTypeShape = (
 	}
 
 	if (type.isObject() && type.getProperties().length === 0) {
-		const targetType = type.getAliasTypeArguments()[1]
-		return [
-			{
-				role: 'record' as const,
-				shape: getProperTypeShape(targetType, atLocation, nextStack),
-				optional: false,
-			},
-		]
+		const targetType = type.getAliasTypeArguments()[1] ?? type.getStringIndexType()
+		if (targetType) {
+			return [
+				{
+					role: 'record' as const,
+					shape: getProperTypeShape(targetType, atLocation, nextStack),
+					optional: false,
+				},
+			]
+		}
 	}
 
 	if (type.isObject()) {
@@ -680,6 +770,21 @@ const getLiteralValueOfNode = (node: Node): string | string[] | unknown[] => {
 	return 'unknown_6'
 }
 
+export const resolveEndpointPath = (node: Node): string | null => {
+	const callExpression = node.getFirstDescendantByKind(SyntaxKind.CallExpression)
+	if (!callExpression) return null
+
+	const firstArg = callExpression.getArguments()[0]
+	if (!firstArg) return null
+
+	const argType = firstArg.getType()
+	if (argType.isStringLiteral()) {
+		return argType.getLiteralValue() as string
+	}
+
+	return null
+}
+
 export const getValuesOfObjectLiteral = (objectLiteralNode: Node<ts.ObjectLiteralExpression>) => {
 	const syntaxListNode = objectLiteralNode.getFirstDescendantByKind(SyntaxKind.SyntaxList)!
 	const assignmentNodes = syntaxListNode.getChildrenOfKind(SyntaxKind.PropertyAssignment)!

package/src/openapi/analyzerModule/parseEndpoint.ts

@@ -11,6 +11,7 @@ import {
 	getValidatorPropertyShape,
 	getValidatorPropertyStringValue,
 	getValuesOfObjectLiteral,
+	resolveEndpointPath,
 } from './nodeParsers'
 
 export const parseEndpoint = (node: Node<ts.Node>, sourceFilePath: string) => {
@@ -22,8 +23,7 @@ export const parseEndpoint = (node: Node<ts.Node>, sourceFilePath: string) => {
 
 	const endpointMethod = parsedEndpointMethod === 'DEL' ? 'DELETE' : parsedEndpointMethod
 
-	const endpointText = node.getFirstDescendantByKind(SyntaxKind.StringLiteral)!.getText() ?? ''
-	const endpointPath = endpointText.substring(1, endpointText.length - 1)
+	const endpointPath = resolveEndpointPath(node) ?? ''
 
 	const endpointData: EndpointData = {
 		method: endpointMethod as 'GET' | 'POST' | 'PUT' | 'PATCH' | 'DELETE',

package/src/openapi/analyzerModule/test/TestCase.ts

@@ -0,0 +1,8 @@
+export const TestCase = {
+	parsesInlineZodNumber: 'parses-inline-zod-number',
+	parsesInlineZodString: 'parses-inline-zod-string',
+	parsesInlineZodObject: 'parses-inline-zod-object',
+	parsesInlineZodNumberArray: 'parses-inline-zod-number-array',
+	parsesInlineZodObjectArray: 'parses-inline-zod-object-array',
+	parsedAliasedZodSchema: 'parses-aliased-zod-schema',
+} as const

package/src/openapi/analyzerModule/test/openApiAnalyzer.spec.data.ts

@@ -550,3 +550,12 @@ router.get('/test/2ec01787-13d0-4512-9cf3-468f409508b7', () => {
 		value: 'foo',
 	}
 })
+
+// Mimics Prisma's JsonValue / JsonObject: an object with an index signature and no own properties
+type JsonValue = string | number | boolean | JsonObject | JsonArray | null
+type JsonObject = { [Key in string]?: JsonValue }
+type JsonArray = JsonValue[]
+
+router.get('/test/c4a1e7b2-9f3d-4e8a-b5c6-7d2f1a3e4b5c', () => {
+	return {} as { data: JsonObject }
+})

package/src/openapi/analyzerModule/test/openApiAnalyzer.spec.ts

@@ -725,6 +725,27 @@ describe('OpenApi Analyzer', () => {
 				expect(endpoint.responses.length).toEqual(1)
 			})
 
+			it('parses return type with index signature object (like Prisma JsonObject) correctly', () => {
+				const endpoint = analyzeEndpointById('c4a1e7b2-9f3d-4e8a-b5c6-7d2f1a3e4b5c')
+
+				expect(endpoint.responses[0].status).toEqual(200)
+				expect(endpoint.responses[0].signature).toEqual([
+					{
+						role: 'property',
+						identifier: 'data',
+						shape: [
+							{
+								role: 'record',
+								shape: expect.anything(),
+								optional: false,
+							},
+						],
+						optional: false,
+					},
+				])
+				expect(endpoint.responses.length).toEqual(1)
+			})
+
 			it('parses no-return endpoint correctly', () => {
 				const endpoint = analyzeEndpointById('196f2937-e369-435f-b239-62eaacaa6fbd')
 

package/src/openapi/analyzerModule/test/openApiAnalyzer.zod.spec.data.ts

@@ -0,0 +1,87 @@
+import { z } from 'zod'
+import { z as valibot } from 'zod'
+
+import { usePathParams } from '../../../hooks/usePathParams'
+import { useRequestBody } from '../../../hooks/useRequestBody'
+import { Router } from '../../../router/Router'
+import { TestCase } from './TestCase'
+
+const router = new Router()
+
+router.post(`/test/${TestCase.parsesInlineZodNumber}/:id`, (ctx) => {
+	usePathParams(ctx, {
+		id: z.number(),
+	})
+
+	useRequestBody(ctx, {
+		data: z.number(),
+	})
+})
+
+router.post(`/test/${TestCase.parsesInlineZodString}/:id`, (ctx) => {
+	usePathParams(ctx, {
+		id: z.string(),
+	})
+
+	useRequestBody(ctx, {
+		data: z.string(),
+	})
+})
+
+router.post(`/test/${TestCase.parsesInlineZodObject}/:id`, (ctx) => {
+	usePathParams(ctx, {
+		id: z.object({
+			value: z.number(),
+		}),
+	})
+
+	useRequestBody(ctx, {
+		data: z.object({
+			value: z.number(),
+		}),
+	})
+})
+
+router.post(`/test/${TestCase.parsesInlineZodNumberArray}/:id`, (ctx) => {
+	usePathParams(ctx, {
+		id: z.array(z.number()),
+	})
+
+	useRequestBody(ctx, {
+		data: z.array(z.number()),
+	})
+})
+
+router.post(`/test/${TestCase.parsesInlineZodObjectArray}/:id`, (ctx) => {
+	usePathParams(ctx, {
+		id: z.array(
+			z.object({
+				value: z.number(),
+			}),
+		),
+	})
+
+	useRequestBody(ctx, {
+		data: z.array(
+			z.object({
+				value: z.number(),
+			}),
+		),
+	})
+})
+
+router.post(`/test/${TestCase.parsedAliasedZodSchema}/:id`, (ctx) => {
+	const schema = valibot.array(
+		valibot.object({
+			value: valibot.number(),
+		}),
+	)
+
+	usePathParams(ctx, {
+		id: schema,
+	})
+
+	useRequestBody(ctx, {
+		data: schema,
+	})
+})

package/src/openapi/analyzerModule/test/openApiAnalyzer.zod.spec.ts

@@ -0,0 +1,178 @@
+import { loadTestData } from '../../../utils/loadTestData'
+import { discoverRouters } from '../../discoveryModule/discoverRouters/discoverRouters'
+import { analyzeSourceFileEndpoints } from '../analyzerModule'
+import { TestCase } from './TestCase'
+
+describe('OpenApi Analyzer (Zod Validator)', () => {
+	describe('when analyzing a test data file', () => {
+		const dataFile = loadTestData('openApiAnalyzer.zod.spec.data.ts')
+		let analysisResult: ReturnType<typeof analyzeSourceFileEndpoints>
+
+		const analyzeEndpointById = (id: string) => {
+			analysisResult = analyzeSourceFileEndpoints(
+				{
+					fileName: 'test',
+					sourceFile: dataFile,
+					routers: discoverRouters(dataFile),
+				},
+				[`/test/${id}`],
+			)
+			const endpoint = analysisResult.find((endpoint) => endpoint.path.startsWith(`/test/${id}`))
+			if (!endpoint) {
+				throw new Error(`No endpoint with id ${id} found!`)
+			}
+			return endpoint
+		}
+
+		describe('zod validators', () => {
+			it('parses inline zod number validators', () => {
+				const endpoint = analyzeEndpointById(TestCase.parsesInlineZodNumber)
+
+				expect(endpoint.requestPathParams[0].identifier).toEqual('id')
+				expect(endpoint.requestPathParams[0].signature).toEqual('number')
+				expect(endpoint.requestPathParams[0].optional).toEqual(false)
+
+				expect(endpoint.objectBody[0].identifier).toEqual('data')
+				expect(endpoint.objectBody[0].signature).toEqual('number')
+				expect(endpoint.objectBody[0].optional).toEqual(false)
+			})
+
+			it('parses inline zod string validators', () => {
+				const endpoint = analyzeEndpointById(TestCase.parsesInlineZodString)
+
+				expect(endpoint.requestPathParams[0].identifier).toEqual('id')
+				expect(endpoint.requestPathParams[0].signature).toEqual('string')
+				expect(endpoint.requestPathParams[0].optional).toEqual(false)
+
+				expect(endpoint.objectBody[0].identifier).toEqual('data')
+				expect(endpoint.objectBody[0].signature).toEqual('string')
+				expect(endpoint.objectBody[0].optional).toEqual(false)
+			})
+
+			it('parses inline zod object validators', () => {
+				const endpoint = analyzeEndpointById(TestCase.parsesInlineZodObject)
+
+				expect(endpoint.requestPathParams[0].identifier).toEqual('id')
+				expect(endpoint.requestPathParams[0].signature).toEqual([
+					{
+						identifier: 'value',
+						optional: false,
+						role: 'property',
+						shape: 'number',
+					},
+				])
+				expect(endpoint.requestPathParams[0].optional).toEqual(false)
+
+				expect(endpoint.objectBody[0].identifier).toEqual('data')
+				expect(endpoint.objectBody[0].signature).toEqual([
+					{
+						identifier: 'value',
+						optional: false,
+						role: 'property',
+						shape: 'number',
+					},
+				])
+				expect(endpoint.objectBody[0].optional).toEqual(false)
+			})
+
+			it('parses inline zod number array validators', () => {
+				const endpoint = analyzeEndpointById(TestCase.parsesInlineZodNumberArray)
+
+				expect(endpoint.requestPathParams[0].identifier).toEqual('id')
+				expect(endpoint.requestPathParams[0].signature).toEqual([
+					{
+						role: 'array',
+						shape: 'number',
+						optional: false,
+					},
+				])
+				expect(endpoint.requestPathParams[0].optional).toEqual(false)
+				expect(endpoint.objectBody[0].identifier).toEqual('data')
+				expect(endpoint.objectBody[0].signature).toEqual([
+					{
+						role: 'array',
+						shape: 'number',
+						optional: false,
+					},
+				])
+				expect(endpoint.objectBody[0].optional).toEqual(false)
+			})
+
+			it('parses inline zod object array validators', () => {
+				const endpoint = analyzeEndpointById(TestCase.parsesInlineZodObjectArray)
+
+				expect(endpoint.requestPathParams[0].identifier).toEqual('id')
+				expect(endpoint.requestPathParams[0].signature).toEqual([
+					{
+						role: 'array',
+						shape: [
+							{
+								identifier: 'value',
+								optional: false,
+								role: 'property',
+								shape: 'number',
+							},
+						],
+						optional: false,
+					},
+				])
+				expect(endpoint.requestPathParams[0].optional).toEqual(false)
+
+				expect(endpoint.objectBody[0].identifier).toEqual('data')
+				expect(endpoint.objectBody[0].signature).toEqual([
+					{
+						role: 'array',
+						shape: [
+							{
+								identifier: 'value',
+								optional: false,
+								role: 'property',
+								shape: 'number',
+							},
+						],
+						optional: false,
+					},
+				])
+				expect(endpoint.objectBody[0].optional).toEqual(false)
+			})
+
+			it('parses aliased zod object array validators', () => {
+				const endpoint = analyzeEndpointById(TestCase.parsedAliasedZodSchema)
+
+				expect(endpoint.requestPathParams[0].identifier).toEqual('id')
+				expect(endpoint.requestPathParams[0].signature).toEqual([
+					{
+						role: 'array',
+						shape: [
+							{
+								identifier: 'value',
+								optional: false,
+								role: 'property',
+								shape: 'number',
+							},
+						],
+						optional: false,
+					},
+				])
+				expect(endpoint.requestPathParams[0].optional).toEqual(false)
+
+				expect(endpoint.objectBody[0].identifier).toEqual('data')
+				expect(endpoint.objectBody[0].signature).toEqual([
+					{
+						role: 'array',
+						shape: [
+							{
+								identifier: 'value',
+								optional: false,
+								role: 'property',
+								shape: 'number',
+							},
+						],
+						optional: false,
+					},
+				])
+				expect(endpoint.objectBody[0].optional).toEqual(false)
+			})
+		})
+	})
+})

package/src/openapi/initOpenApiEngine.ts

@@ -1,20 +1,62 @@
+import * as fs from 'fs'
 import Koa from 'koa'
 
-import { prepareOpenApiSpec } from './analyzerModule/analyzerModule'
+import type * as AnalyzerModule from './analyzerModule/analyzerModule'
+import { OpenApiManager } from './manager/OpenApiManager'
 import { OpenApiRouter } from './router/OpenApiRouter'
 
+type AnalyzerProps = Parameters<typeof AnalyzerModule.prepareOpenApiSpec>[0]
+
+type PrebuiltSpecProps = {
+	/**
+	 * Path to a pre-built OpenAPI spec JSON file.
+	 * When provided, the analyzer is skipped entirely and the spec is served from this file.
+	 * Use this in production to avoid running the TypeScript analyzer on startup.
+	 *
+	 * Generate the spec file at build time using the CLI:
+	 * ```
+	 * moonflower openapi ./openapi-spec.json
+	 * ```
+	 */
+	specPath: string
+}
+
 /**
  * Middleware to initialize the openApi engine.
  * Can be at any position in the middleware execution order.
- * All files with routers or exposed models must be included in `props.sourceFilePaths`.
- * @param props Paths to files to analyze, relative to project root.
+ *
+ * In development, pass analyzer options to generate the spec on startup:
+ * ```
+ * initOpenApiEngine({ tsconfigPath: 'tsconfig.json', sourceFileDiscovery: true })
+ * ```
+ *
+ * In production, pass a pre-built spec file to skip analysis:
+ * ```
+ * initOpenApiEngine({ specPath: './openapi-spec.json' })
+ * ```
  */
-export const initOpenApiEngine = (props: Parameters<typeof prepareOpenApiSpec>[0]) => {
-	prepareOpenApiSpec(props)
+export const initOpenApiEngine = (props: AnalyzerProps | PrebuiltSpecProps) => {
+	const ready =
+		'specPath' in props
+			? loadPrebuiltSpec(props.specPath)
+			: import('./analyzerModule/analyzerModule').then(({ prepareOpenApiSpec }) => prepareOpenApiSpec(props))
 
 	const builtInRoutes = OpenApiRouter.routes()
 	const builtInAllowedMethods = OpenApiRouter.allowedMethods()
-	return (ctx: Koa.ParameterizedContext<any, any>, next: Koa.Next) => {
+	return async (ctx: Koa.ParameterizedContext<any, any>, next: Koa.Next) => {
+		await ready
 		return builtInRoutes(ctx, () => builtInAllowedMethods(ctx, next))
 	}
 }
+
+const loadPrebuiltSpec = (specPath: string) => {
+	const manager = OpenApiManager.getInstance()
+	if (manager.isReady()) {
+		return
+	}
+
+	const content = fs.readFileSync(specPath, 'utf-8')
+	const spec = JSON.parse(content)
+	manager.setPrebuiltSpec(spec)
+	manager.markAsReady()
+}