From 35e624270c276ec693f784010b49a88e218d7741 Mon Sep 17 00:00:00 2001
From: bryantgillespie <hey@bryantgillespie.com>
Date: Mon, 1 Jun 2026 16:35:01 -0400
Subject: [PATCH 1/3] Reduce API reference prerender memory

---
 app/components/ApiEndpoint.vue       |  2 +-
 app/components/ApiInlineMarkdown.vue | 34 +++++++++++++++++
 app/components/ApiParamsField.vue    |  2 +-
 app/utils/flattenSchema.ts           | 56 ++++++++++++++++++++++------
 app/utils/resolveOasRef.ts           | 23 +++++++++++-
 app/utils/responseToExample.ts       | 15 ++++++--
 6 files changed, 114 insertions(+), 18 deletions(-)
 create mode 100644 app/components/ApiInlineMarkdown.vue

diff --git a/app/components/ApiEndpoint.vue b/app/components/ApiEndpoint.vue
index a7a3b7cbb..6c45760ba 100644
--- a/app/components/ApiEndpoint.vue
+++ b/app/components/ApiEndpoint.vue
@@ -125,7 +125,7 @@ const statusCodeDescriptions: StatusCodeDescriptions = {
 						}"
 						class="[&_p]:my-0"
 					>
-						<MDC
+						<ApiInlineMarkdown
 							v-if="param.description"
 							:value="param.description"
 						/>
diff --git a/app/components/ApiInlineMarkdown.vue b/app/components/ApiInlineMarkdown.vue
new file mode 100644
index 000000000..0982fe883
--- /dev/null
+++ b/app/components/ApiInlineMarkdown.vue
@@ -0,0 +1,34 @@
+<script setup lang="ts">
+/**
+ * Renderer for OpenAPI parameter/response descriptions.
+ *
+ * The full <MDC> component spins up the markdown parser + Shiki per instance,
+ * and the API reference renders thousands of these recursively, which exhausts
+ * the prerender heap. The overwhelming majority of descriptions are a single
+ * line of plain text with no markdown, so we render those as a plain paragraph
+ * and avoid the parser entirely.
+ *
+ * Anything containing markdown syntax (inline code, links, emphasis, lists,
+ * code fences, etc.) falls back to <MDC> so its output stays correct.
+ */
+import { computed } from 'vue';
+
+const props = defineProps<{
+	value: string;
+}>();
+
+// Defer to MDC for a faithful render when the description contains any markdown
+// control character or a line break - a plain <p> would collapse paragraph
+// breaks and drop list/heading structure.
+const hasMarkdown = computed(() => /[`*_[\]<>#|\n]|\]\(/.test(props.value));
+</script>
+
+<template>
+	<MDC
+		v-if="hasMarkdown"
+		:value="value"
+	/>
+	<p v-else>
+		{{ value }}
+	</p>
+</template>
diff --git a/app/components/ApiParamsField.vue b/app/components/ApiParamsField.vue
index 0840295c9..19e70bf86 100644
--- a/app/components/ApiParamsField.vue
+++ b/app/components/ApiParamsField.vue
@@ -17,7 +17,7 @@ defineProps<{
 		}"
 		class="[&_p]:my-0"
 	>
-		<MDC
+		<ApiInlineMarkdown
 			v-if="param.description"
 			:key="`description-${param.name}`"
 			:value="param.description"
diff --git a/app/utils/flattenSchema.ts b/app/utils/flattenSchema.ts
index 1401d2e9b..7101dd882 100644
--- a/app/utils/flattenSchema.ts
+++ b/app/utils/flattenSchema.ts
@@ -1,36 +1,70 @@
 import type { OpenAPIObject, ReferenceObject, SchemaObject } from 'openapi3-ts/oas30';
 import type { FlattenedParam } from '~/types';
 
+/**
+ * Cache flattened results for $ref-rooted schemas. Directus schemas are heavily
+ * cross-referential, so the same component schema is flattened many times across
+ * operations; caching by ref string avoids re-walking shared subtrees. Keyed per
+ * spec via a WeakMap so multiple specs (e.g. in tests) stay isolated.
+ */
+const caches = new WeakMap<OpenAPIObject, Map<string, FlattenedParam | null>>();
+
 export default function (openapi: OpenAPIObject, schema: SchemaObject | ReferenceObject): FlattenedParam | null {
-	const parseLevel = (schemaOrRef: SchemaObject | ReferenceObject, name?: string): FlattenedParam | null => {
-		const schema = '$ref' in schemaOrRef ? resolveOasRef<SchemaObject>(openapi, schemaOrRef.$ref) : schemaOrRef;
+	let cache = caches.get(openapi);
+
+	if (!cache) {
+		cache = new Map();
+		caches.set(openapi, cache);
+	}
+
+	// Tracks $refs on the current descent path to break self-referential cycles.
+	const parseLevel = (schemaOrRef: SchemaObject | ReferenceObject, name?: string, seen: Set<string> = new Set()): FlattenedParam | null => {
+		const ref = '$ref' in schemaOrRef ? schemaOrRef.$ref : null;
+
+		if (ref) {
+			if (seen.has(ref)) {
+				// Circular reference - emit a stub instead of recursing forever.
+				return { name, type: 'object', description: undefined };
+			}
+
+			if (cache.has(ref)) {
+				const cached = cache.get(ref)!;
+				return cached ? { ...cached, name } : null;
+			}
+		}
+
+		const schema = ref ? resolveOasRef<SchemaObject>(openapi, ref) : schemaOrRef as SchemaObject;
 		if (!schema) return null;
 
+		const nextSeen = ref ? new Set(seen).add(ref) : seen;
+
 		const type = Array.isArray(schema.type) ? schema.type.join(' | ') : schema.type;
 		const node: FlattenedParam = { name: name, type, description: schema.description };
 
 		if ('anyOf' in schema && schema.anyOf) {
 			node.anyOf = schema.anyOf
-				.map(child => parseLevel(child))
+				.map(child => parseLevel(child, undefined, nextSeen))
 				.filter((child): child is FlattenedParam => child !== null);
-
-			return node;
 		}
-
-		if (schema.type === 'object') {
+		else if (schema.type === 'object') {
 			node.children = Object.entries(schema.properties ?? {})
-				.map(([key, value]) => parseLevel(value, key))
+				.map(([key, value]) => parseLevel(value, key, nextSeen))
 				.filter((child): child is FlattenedParam => child !== null);
 		}
-
-		if (schema.type === 'array') {
-			const parsedItems = parseLevel(schema.items ?? {});
+		else if (schema.type === 'array') {
+			const parsedItems = parseLevel(schema.items ?? {}, undefined, nextSeen);
 
 			if (parsedItems) {
 				node.children = [parsedItems];
 			}
 		}
 
+		// Cache the fully-resolved node for this ref (sans the call-specific name)
+		// so other operations referencing it reuse the result.
+		if (ref) {
+			cache.set(ref, { ...node, name: undefined });
+		}
+
 		return node;
 	};
 
diff --git a/app/utils/resolveOasRef.ts b/app/utils/resolveOasRef.ts
index c7c161383..c69946027 100644
--- a/app/utils/resolveOasRef.ts
+++ b/app/utils/resolveOasRef.ts
@@ -1,12 +1,33 @@
 import { get } from 'lodash-es';
 import type { OpenAPIObject } from 'openapi3-ts/oas30';
 
+/**
+ * Resolved $ref values are stable for a given spec, so cache them by ref string
+ * to avoid repeatedly walking the spec object. Keyed per spec via a WeakMap so
+ * the cache stays correct if more than one spec is used (e.g. in tests) and is
+ * released when a spec is garbage collected.
+ */
+const caches = new WeakMap<OpenAPIObject, Map<string, unknown>>();
+
 /**
  * Resolve a $ref path from the OpenAPI spec object
  *
  * @note This does not support relative refs
  */
 export default function<O = unknown>(spec: OpenAPIObject, path: string): O | null {
+	let cache = caches.get(spec);
+
+	if (!cache) {
+		cache = new Map();
+		caches.set(spec, cache);
+	}
+
+	if (cache.has(path)) {
+		return cache.get(path) as O | null;
+	}
+
 	const pathParts = path.split('/').slice(1);
-	return get(spec, pathParts, null);
+	const resolved = get(spec, pathParts, null) as O | null;
+	cache.set(path, resolved);
+	return resolved;
 }
diff --git a/app/utils/responseToExample.ts b/app/utils/responseToExample.ts
index 5b00ee266..d9df25220 100644
--- a/app/utils/responseToExample.ts
+++ b/app/utils/responseToExample.ts
@@ -14,19 +14,26 @@ export default function (openapi: OpenAPIObject, root: SchemaObject): unknown |
 		return null;
 	}
 
-	const parseLevel = (schemaOrRef: SchemaObject | ReferenceObject): unknown => {
-		const schemaObj = '$ref' in schemaOrRef ? resolveOasRef<SchemaObject>(openapi, schemaOrRef.$ref) : schemaOrRef;
+	// Tracks $refs on the current descent path to break self-referential cycles.
+	const parseLevel = (schemaOrRef: SchemaObject | ReferenceObject, seen: Set<string> = new Set()): unknown => {
+		const ref = '$ref' in schemaOrRef ? schemaOrRef.$ref : null;
+
+		if (ref && seen.has(ref)) return undefined;
+
+		const schemaObj = ref ? resolveOasRef<SchemaObject>(openapi, ref) : schemaOrRef as SchemaObject;
 
 		if (!schemaObj) return undefined;
 
 		if ('example' in schemaObj) return schemaObj.example;
 
+		const nextSeen = ref ? new Set(seen).add(ref) : seen;
+
 		if (schemaObj.type === 'object') {
 			const obj: ExampleObject = {};
 
 			if (schemaObj.properties) {
 				for (const [key, value] of Object.entries(schemaObj.properties)) {
-					const parsedVal = parseLevel(value);
+					const parsedVal = parseLevel(value, nextSeen);
 
 					if (parsedVal !== undefined) {
 						obj[key] = parsedVal;
@@ -39,7 +46,7 @@ export default function (openapi: OpenAPIObject, root: SchemaObject): unknown |
 
 		if (schemaObj.type === 'array') {
 			if (schemaObj.items) {
-				const parsedVal = parseLevel(schemaObj.items);
+				const parsedVal = parseLevel(schemaObj.items, nextSeen);
 				if (parsedVal !== undefined) return [parsedVal];
 				return [];
 			}

From 0e99c1b1ebb2496c7112fd6ca1ba758afa1680df Mon Sep 17 00:00:00 2001
From: bryantgillespie <hey@bryantgillespie.com>
Date: Mon, 1 Jun 2026 16:54:41 -0400
Subject: [PATCH 2/3] Generate API reference page payloads

---
 .gitignore                        |   1 +
 app/components/ApiEndpoint.vue    |  93 ++-------
 app/layouts/api.vue               |   6 +-
 app/pages/api/[tag].vue           |  43 ++--
 app/pages/api/index.vue           |   6 +-
 app/types.ts                      |  45 +++++
 app/utils/codeSamplesMd.ts        |  13 +-
 app/utils/preMd.ts                |   2 +
 nuxt.config.ts                    |  11 +-
 package.json                      |   9 +-
 scripts/generate-api-reference.ts | 325 ++++++++++++++++++++++++++++++
 11 files changed, 428 insertions(+), 126 deletions(-)
 create mode 100644 scripts/generate-api-reference.ts

diff --git a/.gitignore b/.gitignore
index 4b70306eb..55d54301e 100644
--- a/.gitignore
+++ b/.gitignore
@@ -5,6 +5,7 @@
 .nitro
 .cache
 dist
+app/generated/api-reference
 
 # Node dependencies
 node_modules
diff --git a/app/components/ApiEndpoint.vue b/app/components/ApiEndpoint.vue
index 6c45760ba..60487fc09 100644
--- a/app/components/ApiEndpoint.vue
+++ b/app/components/ApiEndpoint.vue
@@ -1,68 +1,15 @@
 <script setup lang="ts">
-import type {
-	OpenAPIObject,
-	RequestBodyObject,
-	SchemaObject,
-} from 'openapi3-ts/oas30';
-import type {
-	DerefedOperationObject,
-	FlattenedOperationObject,
-} from '~/types';
-
-const openapi = inject<OpenAPIObject>('openapi')!;
+import type { ApiReferenceOperation } from '~/types';
 
 const props = defineProps<{
-	operation: FlattenedOperationObject<DerefedOperationObject>;
+	operation: ApiReferenceOperation;
 }>();
 
-const requestBodyObject = computed(() => {
-	if (!props.operation.requestBody) return null;
-
-	return '$ref' in props.operation.requestBody ? resolveOasRef<RequestBodyObject>(openapi, props.operation.requestBody.$ref) : props.operation.requestBody ?? null;
-});
-
-const requestBodySchema = computed(() => {
-	const contentSchema = requestBodyObject.value?.content?.['application/json']?.schema;
-
-	if (contentSchema) {
-		return flattenSchema(openapi, contentSchema);
-	}
-
-	return null;
-});
-
-const responseBodyObjects = computed(() => {
-	return Object.fromEntries(
-		Object.entries(props.operation.responses).map(([code, response]) => {
-			return [
-				code,
-				response && '$ref' in response ? resolveOasRef<RequestBodyObject>(openapi, response.$ref) : response ?? null,
-			];
-		}));
-});
-
-const flattenedResponseBodySchemas = computed(() => {
-	return Object.entries(responseBodyObjects.value).map(([_, response]: [string, RequestBodyObject | null]) => {
-		const contentSchema = response?.content?.['application/json']?.schema;
-
-		if (contentSchema) {
-			return flattenSchema(openapi, contentSchema);
-		}
-
-		return null;
-	});
-});
-
-const responseBodyExample = computed(() => {
-	const responseSchema = responseBodyObjects?.value?.['200']?.content?.['application/json']?.schema
-		|| responseBodyObjects?.value?.['200']?.content?.['application/text']?.schema;
-
-	if (responseSchema) {
-		return responseToExample(openapi, responseSchema);
-	}
-
-	return null;
-});
+const responseTabs = computed(() => props.operation.responses.map((response, index) => ({
+	label: response.code,
+	meta: response,
+	index,
+})));
 
 type StatusCodeDescriptions = {
 	[key: number]: string;
@@ -118,7 +65,7 @@ const statusCodeDescriptions: StatusCodeDescriptions = {
 						v-for="param of operation.parameters"
 						:key="param.name"
 						:name="param.name"
-						:type="(param.schema as SchemaObject)?.type"
+						:type="param.schema?.type"
 						:ui="{
 							root: 'mb-0',
 							description: 'mt-2',
@@ -134,16 +81,16 @@ const statusCodeDescriptions: StatusCodeDescriptions = {
 			</div>
 
 			<div
-				v-if="requestBodyObject && requestBodySchema"
+				v-if="operation.requestBody?.schema"
 				class="mb-12 last:mb-0"
 			>
 				<ProseH4 :id="slugify(operation.summary!) + '-request'">
 					Request Body
 				</ProseH4>
-				<ProseP v-if="requestBodyObject.description">
-					{{ requestBodyObject.description }}
+				<ProseP v-if="operation.requestBody.description">
+					{{ operation.requestBody.description }}
 				</ProseP>
-				<ApiParams :param="requestBodySchema" />
+				<ApiParams :param="operation.requestBody.schema" />
 			</div>
 
 			<div class="mb-12 last:mb-0">
@@ -155,11 +102,7 @@ const statusCodeDescriptions: StatusCodeDescriptions = {
 				</ProseH4>
 				<UTabs
 					variant="link"
-					:items="Object.keys(responseBodyObjects).map((code, index) => ({
-						label: code,
-						meta: responseBodyObjects[code],
-						index,
-					}))"
+					:items="responseTabs"
 					:unmount-on-hide="false"
 				>
 					<template #default="{ item }">
@@ -183,8 +126,8 @@ const statusCodeDescriptions: StatusCodeDescriptions = {
 							{{ item.meta.description }}
 						</div>
 						<ApiParams
-							v-if="flattenedResponseBodySchemas[item.index]"
-							:param="flattenedResponseBodySchemas[item.index]!"
+							v-if="item.meta.schema"
+							:param="item.meta.schema"
 						/>
 					</template>
 				</UTabs>
@@ -192,14 +135,14 @@ const statusCodeDescriptions: StatusCodeDescriptions = {
 		</div>
 		<div class="grow sticky top-16 w-full">
 			<MDC
-				v-if="'x-codeSamples' in operation"
+				v-if="operation['x-codeSamples']?.length"
 				:key="`code-samples-${operation.method}-${operation.path}`"
 				:value="codeSamplesMd(operation)"
 			/>
 			<MDC
-				v-if="responseBodyExample"
+				v-if="operation.responseExample"
 				:key="`response-example-${operation.method}-${operation.path}`"
-				:value="preMd('json', 'Response Example', responseBodyExample)"
+				:value="preMd('json', 'Response Example', operation.responseExample)"
 			/>
 		</div>
 	</UPageBody>
diff --git a/app/layouts/api.vue b/app/layouts/api.vue
index 488331649..61501162f 100644
--- a/app/layouts/api.vue
+++ b/app/layouts/api.vue
@@ -1,9 +1,7 @@
 <script setup lang="ts">
-const { spec: openapi } = await import('@directus/openapi');
+import { apiReferenceNavigation } from '~/generated/api-reference/meta';
 
-provide('openapi', openapi);
-
-const oasNavigation = computed(() => mapOasNavigation(openapi));
+const oasNavigation = apiReferenceNavigation;
 </script>
 
 <template>
diff --git a/app/pages/api/[tag].vue b/app/pages/api/[tag].vue
index 248778234..87fef8755 100644
--- a/app/pages/api/[tag].vue
+++ b/app/pages/api/[tag].vue
@@ -1,42 +1,29 @@
 <script setup lang="ts">
-import type { OpenAPIObject, OperationObject } from 'openapi3-ts/oas30';
-import { METHODS } from '~/constants';
-import type { FlattenedOperationObject, DerefedOperationObject } from '~/types';
-
-const openapi = inject<OpenAPIObject>('openapi')!;
+import type { ApiReferenceTagPage } from '~/types';
 
 definePageMeta({
 	layout: 'api',
 });
 
 const route = useRoute();
-
-const tag = computed(() => {
-	return openapi.tags?.find(tag => tag.name.toLowerCase() === route.params.tag);
+const tagSlug = computed(() => String(route.params.tag));
+const apiReferencePages = import.meta.glob<ApiReferenceTagPage>('../../generated/api-reference/tags/*.ts', {
+	import: 'default',
 });
 
-const operations = computed<FlattenedOperationObject<DerefedOperationObject>[]>(() => {
-	const operations = [];
-
-	for (const [path, pathItemObject] of Object.entries(openapi.paths)) {
-		for (const method of METHODS) {
-			if (pathItemObject[method]) {
-				const operationObject: OperationObject = pathItemObject[method];
+const { data: apiReferencePage } = await useAsyncData(
+	() => `api-reference-${tagSlug.value}`,
+	async () => {
+		const loader = apiReferencePages[`../../generated/api-reference/tags/${tagSlug.value}.ts`];
+		return loader ? await loader() : null;
+	},
+	{ watch: [tagSlug] },
+);
 
-				if (operationObject.tags?.includes(tag.value!.name)) {
-					operations.push({
-						...operationObject,
-						method, path,
-					});
-				}
-			}
-		}
-	}
-
-	return derefOperations(openapi, operations);
-});
+const tag = computed(() => apiReferencePage.value?.tag);
+const operations = computed(() => apiReferencePage.value?.operations ?? []);
 
-if (!tag.value) {
+if (!apiReferencePage.value) {
 	throw createError({ statusCode: 404, statusMessage: 'Page not found', fatal: true });
 }
 </script>
diff --git a/app/pages/api/index.vue b/app/pages/api/index.vue
index d30d747d9..bb7dfdf0f 100644
--- a/app/pages/api/index.vue
+++ b/app/pages/api/index.vue
@@ -1,5 +1,5 @@
 <script setup lang="ts">
-import type { OpenAPIObject } from 'openapi3-ts/oas30';
+import { apiReferenceMeta } from '~/generated/api-reference/meta';
 
 definePageMeta({
 	layout: 'api',
@@ -8,8 +8,6 @@ definePageMeta({
 const route = useRoute();
 const { data: page } = await useAsyncData(route.path, () => queryCollection('content').path(route.path).first());
 
-const openapi = inject<OpenAPIObject>('openapi')!;
-
 if (!page.value) {
 	throw createError({ statusCode: 404, statusMessage: 'Page not found', fatal: true });
 }
@@ -23,7 +21,7 @@ if (!page.value) {
 			:ui="{ title: 'title', headline: 'headline' }"
 		>
 			<template #headline>
-				For Directus v{{ openapi.info.version }}+
+				For Directus v{{ apiReferenceMeta.version }}+
 			</template>
 		</UPageHeader>
 		<UPageBody prose>
diff --git a/app/types.ts b/app/types.ts
index 147cc5f89..8dbac5f83 100644
--- a/app/types.ts
+++ b/app/types.ts
@@ -10,3 +10,48 @@ export interface FlattenedParam {
 	children?: FlattenedParam[];
 	anyOf?: FlattenedParam[];
 }
+
+export interface ApiReferenceCodeSample {
+	label: string;
+	lang: string;
+	source: string;
+}
+
+export interface ApiReferenceParameter {
+	name?: string;
+	description?: string;
+	schema?: {
+		type?: string;
+	};
+}
+
+export interface ApiReferenceRequestBody {
+	description?: string;
+	schema: FlattenedParam | null;
+}
+
+export interface ApiReferenceResponse {
+	code: string;
+	description?: string;
+	schema: FlattenedParam | null;
+}
+
+export interface ApiReferenceOperation {
+	method: string;
+	path: string;
+	summary?: string;
+	description?: string;
+	parameters: ApiReferenceParameter[];
+	requestBody: ApiReferenceRequestBody | null;
+	responses: ApiReferenceResponse[];
+	responseExample: unknown | null;
+	'x-codeSamples'?: ApiReferenceCodeSample[];
+}
+
+export interface ApiReferenceTagPage {
+	tag: {
+		name: string;
+		description?: string;
+	};
+	operations: ApiReferenceOperation[];
+}
diff --git a/app/utils/codeSamplesMd.ts b/app/utils/codeSamplesMd.ts
index 66d0b2056..708efd9c1 100644
--- a/app/utils/codeSamplesMd.ts
+++ b/app/utils/codeSamplesMd.ts
@@ -1,16 +1,11 @@
-import type { FlattenedOperationObject } from '~/types';
-
-export interface CodeSample {
-	label: string;
-	lang: string;
-	source: string;
-}
+import preMd from '~/utils/preMd';
+import type { ApiReferenceCodeSample } from '~/types';
 
 /**
  * Convert our @directus/openapi x-codeSamples to valid markdown codeblocks.
  * This allows them to be rendered with MDC
  */
-export default function codeSamplesMd(operation: FlattenedOperationObject) {
+export default function codeSamplesMd(operation: { method: string; path: string; 'x-codeSamples'?: ApiReferenceCodeSample[] }) {
 	let md = '::code-group{sync="api-consumer"}';
 
 	const { method, path } = operation;
@@ -21,7 +16,7 @@ ${method.toUpperCase()} ${path}
 \`\`\`
 `;
 
-	const samples = operation['x-codeSamples'] as CodeSample[];
+	const samples = operation['x-codeSamples'] ?? [];
 
 	for (const { lang, source, label } of samples) {
 		md += preMd(lang, label, source);
diff --git a/app/utils/preMd.ts b/app/utils/preMd.ts
index b01de86ec..830b25e0d 100644
--- a/app/utils/preMd.ts
+++ b/app/utils/preMd.ts
@@ -1,3 +1,5 @@
+import linguistToShiki from '~/utils/linguistToShiki';
+
 export default function (lang: string, label: string, source: unknown) {
 	return `
 \`\`\`${linguistToShiki(lang)} [${label}]
diff --git a/nuxt.config.ts b/nuxt.config.ts
index cd0bd968a..c3e79d09d 100644
--- a/nuxt.config.ts
+++ b/nuxt.config.ts
@@ -1,5 +1,4 @@
 import { existsSync, readFileSync } from 'node:fs';
-import { spec as openapi } from '@directus/openapi';
 import type { NitroConfig } from 'nitropack';
 import { resolveBranchTypesenseAlias } from './lib/typesenseAlias';
 
@@ -27,8 +26,16 @@ function loadRedirectRouteRules(): NitroConfig['routeRules'] {
 	return rules;
 }
 
+function loadApiReferencePrerenderRoutes(): string[] {
+	const path = './app/generated/api-reference/routes.json';
+	if (!existsSync(path)) return [];
+	const raw = readFileSync(path, 'utf8').trim();
+	if (!raw) return [];
+	return JSON.parse(raw) as string[];
+}
+
 const typesenseCollection = process.env.TYPESENSE_COLLECTION || resolveBranchTypesenseAlias() || undefined;
-const apiReferencePrerenderRoutes = openapi.tags?.map(tag => `/api/${tag.name.toLowerCase()}`) ?? [];
+const apiReferencePrerenderRoutes = loadApiReferencePrerenderRoutes();
 
 // https://nuxt.com/docs/api/configuration/nuxt-config
 export default defineNuxtConfig({
diff --git a/package.json b/package.json
index 328f2d771..0a7756393 100644
--- a/package.json
+++ b/package.json
@@ -3,11 +3,12 @@
 	"private": true,
 	"type": "module",
 	"scripts": {
-		"build": "nuxt build",
-		"dev": "nuxt dev",
-		"generate": "nuxt generate",
+		"api-ref:generate": "tsx scripts/generate-api-reference.ts",
+		"build": "tsx scripts/generate-api-reference.ts && nuxt build",
+		"dev": "tsx scripts/generate-api-reference.ts && nuxt dev",
+		"generate": "tsx scripts/generate-api-reference.ts && nuxt generate",
 		"preview": "nuxt preview",
-		"postinstall": "node scripts/setup-hooks.ts && nuxt prepare",
+		"postinstall": "node scripts/setup-hooks.ts && tsx scripts/generate-api-reference.ts && nuxt prepare",
 		"stable-ids:ensure": "node scripts/ensure-stable-ids.ts",
 		"stable-ids:check": "node scripts/check-stable-ids.ts",
 		"redirects:sync": "node scripts/redirects-sync.ts --write-deterministic --fail-on-unresolved",
diff --git a/scripts/generate-api-reference.ts b/scripts/generate-api-reference.ts
new file mode 100644
index 000000000..44cc646e2
--- /dev/null
+++ b/scripts/generate-api-reference.ts
@@ -0,0 +1,325 @@
+import { existsSync } from 'node:fs';
+import { mkdir, readFile, readdir, rm, writeFile } from 'node:fs/promises';
+import { dirname, join } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { spec as openapi } from '@directus/openapi';
+import { get } from 'lodash-es';
+import type {
+	OpenAPIObject,
+	OperationObject,
+	ParameterObject,
+	PathItemObject,
+	ReferenceObject,
+	RequestBodyObject,
+	ResponseObject,
+	SchemaObject,
+} from 'openapi3-ts/oas30';
+import type {
+	ApiReferenceCodeSample,
+	ApiReferenceOperation,
+	ApiReferenceParameter,
+	ApiReferenceResponse,
+	ApiReferenceTagPage,
+	FlattenedParam,
+} from '../app/types.ts';
+
+const root = join(dirname(fileURLToPath(import.meta.url)), '..');
+const outputDir = join(root, 'app/generated/api-reference');
+const tagsDir = join(outputDir, 'tags');
+
+const methods: (keyof PathItemObject)[] = [
+	'get',
+	'put',
+	'post',
+	'delete',
+	'options',
+	'head',
+	'patch',
+	'trace',
+];
+
+const refCache = new Map<string, unknown>();
+const flattenCache = new Map<string, FlattenedParam | null>();
+
+function slugify(val: string): string {
+	return val
+		.replace(/[!"#$%&'()*+,/:;<=>?@[\\\]^`{|}~]/g, '')
+		.replace(/(\s|\.)/g, '-')
+		.replace(/<(?:.|\n)*?>/gm, '')
+		.replace(/—/g, '--')
+		.replace(/-{2,}/g, '-')
+		.toLowerCase();
+}
+
+function decodePointerPart(part: string): string {
+	return part.replace(/~1/g, '/').replace(/~0/g, '~');
+}
+
+function resolveRef<O = unknown>(spec: OpenAPIObject, path: string): O | null {
+	if (refCache.has(path)) return refCache.get(path) as O | null;
+	if (!path.startsWith('#/')) return null;
+
+	const pathParts = path.slice(2).split('/').map(decodePointerPart);
+	const resolved = get(spec, pathParts, null) as O | null;
+	refCache.set(path, resolved);
+	return resolved;
+}
+
+function resolveSchema(schemaOrRef: SchemaObject | ReferenceObject): SchemaObject | null {
+	return '$ref' in schemaOrRef ? resolveRef<SchemaObject>(openapi, schemaOrRef.$ref) : schemaOrRef;
+}
+
+function flattenSchema(schemaOrRef: SchemaObject | ReferenceObject, name?: string, seen: Set<string> = new Set()): FlattenedParam | null {
+	const ref = '$ref' in schemaOrRef ? schemaOrRef.$ref : null;
+
+	if (ref) {
+		if (seen.has(ref)) return { name, type: 'object', description: undefined };
+		if (flattenCache.has(ref)) {
+			const cached = flattenCache.get(ref)!;
+			return cached ? { ...cached, name } : null;
+		}
+	}
+
+	const schema = ref ? resolveRef<SchemaObject>(openapi, ref) : schemaOrRef as SchemaObject;
+	if (!schema) return null;
+
+	const nextSeen = ref ? new Set(seen).add(ref) : seen;
+	const type = Array.isArray(schema.type) ? schema.type.join(' | ') : schema.type;
+	const node: FlattenedParam = { name, type, description: schema.description };
+
+	if ('anyOf' in schema && schema.anyOf) {
+		node.anyOf = schema.anyOf
+			.map(child => flattenSchema(child, undefined, nextSeen))
+			.filter((child): child is FlattenedParam => child !== null);
+	}
+	else if (schema.type === 'object') {
+		node.children = Object.entries(schema.properties ?? {})
+			.map(([key, value]) => flattenSchema(value, key, nextSeen))
+			.filter((child): child is FlattenedParam => child !== null);
+	}
+	else if (schema.type === 'array') {
+		const parsedItems = flattenSchema(schema.items ?? {}, undefined, nextSeen);
+		if (parsedItems) node.children = [parsedItems];
+	}
+
+	if (ref) flattenCache.set(ref, { ...node, name: undefined });
+	return node;
+}
+
+function responseToExample(root: SchemaObject): unknown | null {
+	if (root.type !== 'object' && !(root.type === 'array' || root.type === 'string')) return null;
+
+	const parseLevel = (schemaOrRef: SchemaObject | ReferenceObject, seen: Set<string> = new Set()): unknown => {
+		const ref = '$ref' in schemaOrRef ? schemaOrRef.$ref : null;
+		if (ref && seen.has(ref)) return undefined;
+
+		const schemaObj = ref ? resolveRef<SchemaObject>(openapi, ref) : schemaOrRef as SchemaObject;
+		if (!schemaObj) return undefined;
+		if ('example' in schemaObj) return schemaObj.example;
+
+		const nextSeen = ref ? new Set(seen).add(ref) : seen;
+
+		if (schemaObj.type === 'object') {
+			const obj: Record<string, unknown> = {};
+
+			if (schemaObj.properties) {
+				for (const [key, value] of Object.entries(schemaObj.properties)) {
+					const parsedVal = parseLevel(value, nextSeen);
+					if (parsedVal !== undefined) obj[key] = parsedVal;
+				}
+			}
+
+			return obj;
+		}
+
+		if (schemaObj.type === 'array') {
+			if (schemaObj.items) {
+				const parsedVal = parseLevel(schemaObj.items, nextSeen);
+				if (parsedVal !== undefined) return [parsedVal];
+				return [];
+			}
+
+			return [];
+		}
+	};
+
+	const exampleObject = parseLevel(root);
+	if (root.type === 'array') return [exampleObject];
+	return exampleObject ?? null;
+}
+
+function resolveRequestBody(requestBody: OperationObject['requestBody']): RequestBodyObject | null {
+	if (!requestBody) return null;
+	return '$ref' in requestBody ? resolveRef<RequestBodyObject>(openapi, requestBody.$ref) : requestBody;
+}
+
+function resolveResponse(response: ReferenceObject | ResponseObject): ResponseObject | null {
+	return '$ref' in response ? resolveRef<ResponseObject>(openapi, response.$ref) : response;
+}
+
+function resolveParameter(parameter: ReferenceObject | ParameterObject): ParameterObject | null {
+	return '$ref' in parameter ? resolveRef<ParameterObject>(openapi, parameter.$ref) : parameter;
+}
+
+function apiParameter(parameter: ParameterObject): ApiReferenceParameter {
+	const schema = parameter.schema ? resolveSchema(parameter.schema) : null;
+	const type = Array.isArray(schema?.type) ? schema.type.join(' | ') : schema?.type;
+
+	return {
+		name: parameter.name,
+		description: parameter.description,
+		schema: type ? { type } : undefined,
+	};
+}
+
+function requestBodyData(operation: OperationObject): ApiReferenceOperation['requestBody'] {
+	const requestBody = resolveRequestBody(operation.requestBody);
+	if (!requestBody) return null;
+
+	const contentSchema = requestBody.content?.['application/json']?.schema;
+	return {
+		description: requestBody.description,
+		schema: contentSchema ? flattenSchema(contentSchema) : null,
+	};
+}
+
+function responseData(operation: OperationObject): ApiReferenceResponse[] {
+	return Object.entries(operation.responses ?? {}).map(([code, responseOrRef]) => {
+		const response = resolveResponse(responseOrRef);
+		const contentSchema = response?.content?.['application/json']?.schema;
+
+		return {
+			code,
+			description: response?.description,
+			schema: contentSchema ? flattenSchema(contentSchema) : null,
+		};
+	});
+}
+
+function responseExample(operation: OperationObject): unknown | null {
+	const responseRef = operation.responses?.['200'];
+	if (!responseRef) return null;
+
+	const response = resolveResponse(responseRef);
+	const responseSchema = response?.content?.['application/json']?.schema
+		?? response?.content?.['application/text']?.schema;
+	const schema = responseSchema ? resolveSchema(responseSchema) : null;
+
+	return schema ? responseToExample(schema) : null;
+}
+
+function apiOperation(path: string, method: keyof PathItemObject, operation: OperationObject): ApiReferenceOperation {
+	const codeSamples = (operation as OperationObject & { 'x-codeSamples'?: ApiReferenceCodeSample[] })['x-codeSamples'];
+
+	return {
+		method,
+		path,
+		summary: operation.summary,
+		description: operation.description,
+		parameters: (operation.parameters ?? [])
+			.map(resolveParameter)
+			.filter((parameter): parameter is ParameterObject => parameter !== null)
+			.map(apiParameter),
+		requestBody: requestBodyData(operation),
+		responses: responseData(operation),
+		responseExample: responseExample(operation),
+		...(codeSamples?.length ? { 'x-codeSamples': codeSamples } : {}),
+	};
+}
+
+function operationsByTag() {
+	const byTag = new Map<string, ApiReferenceOperation[]>();
+
+	for (const [path, pathItemObject] of Object.entries(openapi.paths)) {
+		for (const method of methods) {
+			const operation = pathItemObject[method] as OperationObject | undefined;
+			if (!operation) continue;
+
+			for (const tag of operation.tags ?? []) {
+				byTag.set(tag, [...(byTag.get(tag) ?? []), apiOperation(path, method, operation)]);
+			}
+		}
+	}
+
+	return byTag;
+}
+
+function navigation(byTag: Map<string, ApiReferenceOperation[]>) {
+	return [...byTag.entries()].map(([tag, operations]) => ({
+		title: tag,
+		to: `/api/${tag.toLowerCase()}`,
+		path: `/api/${tag.toLowerCase()}`,
+		children: operations.map(operation => ({
+			title: operation.summary ?? operation.path,
+			path: `/api/${tag.toLowerCase()}#${slugify(operation.summary!)}`,
+			exact: true,
+			exactHash: true,
+		})),
+	}));
+}
+
+async function writeIfChanged(path: string, content: string) {
+	if (existsSync(path)) {
+		const current = await readFile(path, 'utf8');
+		if (current === content) return;
+	}
+
+	await writeFile(path, content);
+}
+
+async function cleanOldTagFiles(validFiles: Set<string>) {
+	if (!existsSync(tagsDir)) return;
+
+	for (const file of await readdir(tagsDir)) {
+		if (file.endsWith('.ts') && !validFiles.has(file)) {
+			await rm(join(tagsDir, file));
+		}
+	}
+}
+
+async function main() {
+	await mkdir(tagsDir, { recursive: true });
+
+	const byTag = operationsByTag();
+	const validFiles = new Set<string>();
+	const routes: string[] = [];
+
+	for (const tag of openapi.tags ?? []) {
+		const operations = byTag.get(tag.name);
+		if (!operations?.length) continue;
+
+		const slug = tag.name.toLowerCase();
+		const fileName = `${slug}.ts`;
+		const page: ApiReferenceTagPage = {
+			tag: {
+				name: tag.name,
+				description: tag.description,
+			},
+			operations,
+		};
+
+		validFiles.add(fileName);
+		routes.push(`/api/${slug}`);
+
+		await writeIfChanged(
+			join(tagsDir, fileName),
+			`// Generated by scripts/generate-api-reference.ts\nimport type { ApiReferenceTagPage } from '~/types';\n\nexport default ${JSON.stringify(page, null, '\t')} satisfies ApiReferenceTagPage;\n`,
+		);
+	}
+
+	await cleanOldTagFiles(validFiles);
+
+	await writeIfChanged(
+		join(outputDir, 'meta.ts'),
+		`// Generated by scripts/generate-api-reference.ts\n\nexport const apiReferenceMeta = ${JSON.stringify({ version: openapi.info.version }, null, '\t')} as const;\n\nexport const apiReferenceNavigation = ${JSON.stringify(navigation(byTag), null, '\t')} as const;\n`,
+	);
+
+	await writeIfChanged(
+		join(outputDir, 'routes.json'),
+		`${JSON.stringify(routes, null, '\t')}\n`,
+	);
+
+	console.log(`Generated API reference data for ${routes.length} tags`);
+}
+
+await main();

From 34a1e17e72e46740e7aca23c98d3275853a985d8 Mon Sep 17 00:00:00 2001
From: bryantgillespie <hey@bryantgillespie.com>
Date: Mon, 1 Jun 2026 17:38:11 -0400
Subject: [PATCH 3/3] Remove unused API reference runtime walkers

---
 app/constants.ts                  | 14 ------
 app/types.ts                      |  5 ---
 app/utils/derefOperations.ts      | 23 ----------
 app/utils/flattenSchema.ts        | 72 -------------------------------
 app/utils/isValidMethod.ts        |  5 ---
 app/utils/mapOasNavigation.ts     | 41 ------------------
 app/utils/resolveOasRef.ts        | 33 --------------
 app/utils/responseToExample.ts    | 62 --------------------------
 nuxt.config.ts                    | 17 ++++++--
 scripts/generate-api-reference.ts | 31 ++++++++-----
 scripts/nuxt-shims.d.ts           |  4 --
 11 files changed, 34 insertions(+), 273 deletions(-)
 delete mode 100644 app/constants.ts
 delete mode 100644 app/utils/derefOperations.ts
 delete mode 100644 app/utils/flattenSchema.ts
 delete mode 100644 app/utils/isValidMethod.ts
 delete mode 100644 app/utils/mapOasNavigation.ts
 delete mode 100644 app/utils/resolveOasRef.ts
 delete mode 100644 app/utils/responseToExample.ts
 delete mode 100644 scripts/nuxt-shims.d.ts

diff --git a/app/constants.ts b/app/constants.ts
deleted file mode 100644
index 0ba92f5f7..000000000
--- a/app/constants.ts
+++ /dev/null
@@ -1,14 +0,0 @@
-import type {
-	PathItemObject,
-} from 'openapi3-ts/oas30';
-
-export const METHODS: (keyof PathItemObject)[] = [
-	'get',
-	'put',
-	'post',
-	'delete',
-	'options',
-	'head',
-	'patch',
-	'trace',
-] as const;
diff --git a/app/types.ts b/app/types.ts
index 8dbac5f83..31916965c 100644
--- a/app/types.ts
+++ b/app/types.ts
@@ -1,8 +1,3 @@
-import type { OperationObject, ParameterObject } from 'openapi3-ts/oas30';
-
-export type DerefedOperationObject<O = OperationObject> = O & { parameters: ParameterObject[] };
-export type FlattenedOperationObject<O = OperationObject> = O & { method: string; path: string };
-
 export interface FlattenedParam {
 	name: string | undefined;
 	type: string | undefined;
diff --git a/app/utils/derefOperations.ts b/app/utils/derefOperations.ts
deleted file mode 100644
index b925f4124..000000000
--- a/app/utils/derefOperations.ts
+++ /dev/null
@@ -1,23 +0,0 @@
-import type { OpenAPIObject, OperationObject, ParameterObject } from 'openapi3-ts/oas30';
-
-/**
- * Deref $ref properties in OAS paths
- *
- * @param spec - Full OAS spec
- * @param operations - Operations to deref
- */
-
-export default function<O extends OperationObject>(spec: OpenAPIObject, operations: O[]): (O & { parameters: ParameterObject[] })[] {
-	return operations.map((operation) => {
-		return {
-			...operation,
-			parameters: operation.parameters?.map((part) => {
-				if ('$ref' in part) {
-					return resolveOasRef<ParameterObject>(spec, part.$ref);
-				}
-
-				return part;
-			}).filter(part => part !== null) ?? [],
-		};
-	});
-}
diff --git a/app/utils/flattenSchema.ts b/app/utils/flattenSchema.ts
deleted file mode 100644
index 7101dd882..000000000
--- a/app/utils/flattenSchema.ts
+++ /dev/null
@@ -1,72 +0,0 @@
-import type { OpenAPIObject, ReferenceObject, SchemaObject } from 'openapi3-ts/oas30';
-import type { FlattenedParam } from '~/types';
-
-/**
- * Cache flattened results for $ref-rooted schemas. Directus schemas are heavily
- * cross-referential, so the same component schema is flattened many times across
- * operations; caching by ref string avoids re-walking shared subtrees. Keyed per
- * spec via a WeakMap so multiple specs (e.g. in tests) stay isolated.
- */
-const caches = new WeakMap<OpenAPIObject, Map<string, FlattenedParam | null>>();
-
-export default function (openapi: OpenAPIObject, schema: SchemaObject | ReferenceObject): FlattenedParam | null {
-	let cache = caches.get(openapi);
-
-	if (!cache) {
-		cache = new Map();
-		caches.set(openapi, cache);
-	}
-
-	// Tracks $refs on the current descent path to break self-referential cycles.
-	const parseLevel = (schemaOrRef: SchemaObject | ReferenceObject, name?: string, seen: Set<string> = new Set()): FlattenedParam | null => {
-		const ref = '$ref' in schemaOrRef ? schemaOrRef.$ref : null;
-
-		if (ref) {
-			if (seen.has(ref)) {
-				// Circular reference - emit a stub instead of recursing forever.
-				return { name, type: 'object', description: undefined };
-			}
-
-			if (cache.has(ref)) {
-				const cached = cache.get(ref)!;
-				return cached ? { ...cached, name } : null;
-			}
-		}
-
-		const schema = ref ? resolveOasRef<SchemaObject>(openapi, ref) : schemaOrRef as SchemaObject;
-		if (!schema) return null;
-
-		const nextSeen = ref ? new Set(seen).add(ref) : seen;
-
-		const type = Array.isArray(schema.type) ? schema.type.join(' | ') : schema.type;
-		const node: FlattenedParam = { name: name, type, description: schema.description };
-
-		if ('anyOf' in schema && schema.anyOf) {
-			node.anyOf = schema.anyOf
-				.map(child => parseLevel(child, undefined, nextSeen))
-				.filter((child): child is FlattenedParam => child !== null);
-		}
-		else if (schema.type === 'object') {
-			node.children = Object.entries(schema.properties ?? {})
-				.map(([key, value]) => parseLevel(value, key, nextSeen))
-				.filter((child): child is FlattenedParam => child !== null);
-		}
-		else if (schema.type === 'array') {
-			const parsedItems = parseLevel(schema.items ?? {}, undefined, nextSeen);
-
-			if (parsedItems) {
-				node.children = [parsedItems];
-			}
-		}
-
-		// Cache the fully-resolved node for this ref (sans the call-specific name)
-		// so other operations referencing it reuse the result.
-		if (ref) {
-			cache.set(ref, { ...node, name: undefined });
-		}
-
-		return node;
-	};
-
-	return parseLevel(schema);
-}
diff --git a/app/utils/isValidMethod.ts b/app/utils/isValidMethod.ts
deleted file mode 100644
index 06eab5a21..000000000
--- a/app/utils/isValidMethod.ts
+++ /dev/null
@@ -1,5 +0,0 @@
-import { METHODS } from '~/constants';
-
-export default function (method: string): method is typeof METHODS[number] {
-	return METHODS.includes(method as typeof METHODS[number]);
-}
diff --git a/app/utils/mapOasNavigation.ts b/app/utils/mapOasNavigation.ts
deleted file mode 100644
index e5888d4c6..000000000
--- a/app/utils/mapOasNavigation.ts
+++ /dev/null
@@ -1,41 +0,0 @@
-import type {
-	OpenAPIObject,
-	OperationObject,
-} from 'openapi3-ts/oas30';
-import type { ContentNavigationItem } from '@nuxt/content';
-import { METHODS } from '@/constants';
-import slugify from '~/utils/slugify';
-
-export default function (spec: OpenAPIObject): ContentNavigationItem[] {
-	const byTag: Record<string, ContentNavigationItem[]> = {};
-
-	for (const [path, pathItemObject] of Object.entries(spec.paths)) {
-		for (const method of METHODS) {
-			if (pathItemObject[method]) {
-				const operationObject: OperationObject = pathItemObject[method];
-
-				for (const tag of operationObject.tags ?? []) {
-					if (!byTag[tag]) {
-						byTag[tag] = [];
-					}
-
-					byTag[tag].push({
-						title: operationObject.summary ?? path,
-						path: `/api/${tag.toLowerCase()}#${slugify(operationObject.summary!)}`,
-						exact: true,
-						exactHash: true,
-					});
-				}
-			}
-		}
-	}
-
-	return Object.entries(byTag).map(([tag, links]) => {
-		return {
-			title: tag,
-			to: `/api/${tag.toLowerCase()}`,
-			path: `/api/${tag.toLowerCase()}`,
-			children: links,
-		};
-	});
-}
diff --git a/app/utils/resolveOasRef.ts b/app/utils/resolveOasRef.ts
deleted file mode 100644
index c69946027..000000000
--- a/app/utils/resolveOasRef.ts
+++ /dev/null
@@ -1,33 +0,0 @@
-import { get } from 'lodash-es';
-import type { OpenAPIObject } from 'openapi3-ts/oas30';
-
-/**
- * Resolved $ref values are stable for a given spec, so cache them by ref string
- * to avoid repeatedly walking the spec object. Keyed per spec via a WeakMap so
- * the cache stays correct if more than one spec is used (e.g. in tests) and is
- * released when a spec is garbage collected.
- */
-const caches = new WeakMap<OpenAPIObject, Map<string, unknown>>();
-
-/**
- * Resolve a $ref path from the OpenAPI spec object
- *
- * @note This does not support relative refs
- */
-export default function<O = unknown>(spec: OpenAPIObject, path: string): O | null {
-	let cache = caches.get(spec);
-
-	if (!cache) {
-		cache = new Map();
-		caches.set(spec, cache);
-	}
-
-	if (cache.has(path)) {
-		return cache.get(path) as O | null;
-	}
-
-	const pathParts = path.split('/').slice(1);
-	const resolved = get(spec, pathParts, null) as O | null;
-	cache.set(path, resolved);
-	return resolved;
-}
diff --git a/app/utils/responseToExample.ts b/app/utils/responseToExample.ts
deleted file mode 100644
index d9df25220..000000000
--- a/app/utils/responseToExample.ts
+++ /dev/null
@@ -1,62 +0,0 @@
-import type { OpenAPIObject, ReferenceObject, SchemaObject } from 'openapi3-ts/oas30';
-
-export type ExampleObject = Record<string, unknown>;
-
-/**
- * Converts an openapi response definition to an example object
- * @param openapi - Full openapi spec to pull references from
- * @param responseSchema - Response schema to convert to example objects
- *
- * @note this expects the top level responseSchema to be an object or array of things
- */
-export default function (openapi: OpenAPIObject, root: SchemaObject): unknown | null {
-	if (root.type !== 'object' && !(root.type === 'array' || root.type === 'string')) {
-		return null;
-	}
-
-	// Tracks $refs on the current descent path to break self-referential cycles.
-	const parseLevel = (schemaOrRef: SchemaObject | ReferenceObject, seen: Set<string> = new Set()): unknown => {
-		const ref = '$ref' in schemaOrRef ? schemaOrRef.$ref : null;
-
-		if (ref && seen.has(ref)) return undefined;
-
-		const schemaObj = ref ? resolveOasRef<SchemaObject>(openapi, ref) : schemaOrRef as SchemaObject;
-
-		if (!schemaObj) return undefined;
-
-		if ('example' in schemaObj) return schemaObj.example;
-
-		const nextSeen = ref ? new Set(seen).add(ref) : seen;
-
-		if (schemaObj.type === 'object') {
-			const obj: ExampleObject = {};
-
-			if (schemaObj.properties) {
-				for (const [key, value] of Object.entries(schemaObj.properties)) {
-					const parsedVal = parseLevel(value, nextSeen);
-
-					if (parsedVal !== undefined) {
-						obj[key] = parsedVal;
-					}
-				}
-			}
-
-			return obj;
-		}
-
-		if (schemaObj.type === 'array') {
-			if (schemaObj.items) {
-				const parsedVal = parseLevel(schemaObj.items, nextSeen);
-				if (parsedVal !== undefined) return [parsedVal];
-				return [];
-			}
-
-			return [];
-		}
-	};
-
-	const exampleObject: unknown = parseLevel(root);
-
-	if (root.type === 'array') return [exampleObject];
-	return exampleObject;
-}
diff --git a/nuxt.config.ts b/nuxt.config.ts
index c3e79d09d..10e8b0f79 100644
--- a/nuxt.config.ts
+++ b/nuxt.config.ts
@@ -28,10 +28,21 @@ function loadRedirectRouteRules(): NitroConfig['routeRules'] {
 
 function loadApiReferencePrerenderRoutes(): string[] {
 	const path = './app/generated/api-reference/routes.json';
-	if (!existsSync(path)) return [];
+	if (!existsSync(path)) {
+		throw new Error('Missing generated API reference routes. Run `pnpm api-ref:generate` before Nuxt.');
+	}
+
 	const raw = readFileSync(path, 'utf8').trim();
-	if (!raw) return [];
-	return JSON.parse(raw) as string[];
+	if (!raw) {
+		throw new Error('Generated API reference routes are empty. Run `pnpm api-ref:generate`.');
+	}
+
+	const routes = JSON.parse(raw) as string[];
+	if (routes.length === 0) {
+		throw new Error('Generated API reference routes are empty. Run `pnpm api-ref:generate`.');
+	}
+
+	return routes;
 }
 
 const typesenseCollection = process.env.TYPESENSE_COLLECTION || resolveBranchTypesenseAlias() || undefined;
diff --git a/scripts/generate-api-reference.ts b/scripts/generate-api-reference.ts
index 44cc646e2..8c6ef8526 100644
--- a/scripts/generate-api-reference.ts
+++ b/scripts/generate-api-reference.ts
@@ -245,17 +245,26 @@ function operationsByTag() {
 }
 
 function navigation(byTag: Map<string, ApiReferenceOperation[]>) {
-	return [...byTag.entries()].map(([tag, operations]) => ({
-		title: tag,
-		to: `/api/${tag.toLowerCase()}`,
-		path: `/api/${tag.toLowerCase()}`,
-		children: operations.map(operation => ({
-			title: operation.summary ?? operation.path,
-			path: `/api/${tag.toLowerCase()}#${slugify(operation.summary!)}`,
-			exact: true,
-			exactHash: true,
-		})),
-	}));
+	return (openapi.tags ?? [])
+		.map((tag) => {
+			const operations = byTag.get(tag.name);
+			if (!operations?.length) return null;
+
+			const slug = tag.name.toLowerCase();
+
+			return {
+				title: tag.name,
+				to: `/api/${slug}`,
+				path: `/api/${slug}`,
+				children: operations.map(operation => ({
+					title: operation.summary ?? operation.path,
+					path: `/api/${slug}#${slugify(operation.summary!)}`,
+					exact: true,
+					exactHash: true,
+				})),
+			};
+		})
+		.filter(item => item !== null);
 }
 
 async function writeIfChanged(path: string, content: string) {
diff --git a/scripts/nuxt-shims.d.ts b/scripts/nuxt-shims.d.ts
deleted file mode 100644
index 58d8155c2..000000000
--- a/scripts/nuxt-shims.d.ts
+++ /dev/null
@@ -1,4 +0,0 @@
-declare const resolveOasRef: typeof import('../app/utils/resolveOasRef.ts').default;
-declare const flattenSchema: typeof import('../app/utils/flattenSchema.ts').default;
-declare const responseToExample: typeof import('../app/utils/responseToExample.ts').default;
-declare const linguistToShiki: typeof import('../app/utils/linguistToShiki.ts').default;