docs: fixes and refactoring for API reference (#9708)

* docs: fixes and refactoring for API reference

* add route caching

* remove caching

* use next cache

www/apps/api-reference/app/admin/page.tsx

@@ -3,22 +3,35 @@ import AdminContent from "../_mdx/admin.mdx"
 import Tags from "@/components/Tags"
 import PageTitleProvider from "@/providers/page-title"
 import { H1 } from "docs-ui"
+import { getBaseSpecs } from "../../lib"
+import BaseSpecsProvider from "../../providers/base-specs"
+import clsx from "clsx"
+
+const AdminPage = async () => {
+  const data = await getBaseSpecs("admin")
 
-const ReferencePage = async () => {
   return (
-    <AreaProvider area={"admin"}>
-      <PageTitleProvider>
-        <H1 className="!h2-docs scroll-m-56 lg:pl-4" id="introduction">
-          Medusa V2 Admin API Reference
-        </H1>
-        <AdminContent />
-        <Tags />
-      </PageTitleProvider>
-    </AreaProvider>
+    <BaseSpecsProvider baseSpecs={data}>
+      <AreaProvider area={"admin"}>
+        <PageTitleProvider>
+          <H1
+            className={clsx(
+              "!h2-docs lg:pl-4",
+              "scroll-m-[184px] lg:scroll-m-[264px]"
+            )}
+            id="introduction"
+          >
+            Medusa V2 Admin API Reference
+          </H1>
+          <AdminContent />
+          <Tags tags={data?.tags} />
+        </PageTitleProvider>
+      </AreaProvider>
+    </BaseSpecsProvider>
   )
 }
 
-export default ReferencePage
+export default AdminPage
 
 export function generateMetadata() {
   return {

www/apps/api-reference/app/api/schema/route.ts

@@ -1,9 +1,7 @@
 import { NextResponse } from "next/server"
-import { SchemaObject } from "../../../types/openapi"
 import path from "path"
-import { existsSync, promises as fs } from "fs"
-import { parseDocument } from "yaml"
-import dereference from "../../../utils/dereference"
+import { existsSync } from "fs"
+import getSchemaContent from "../../../utils/get-schema-content"
 
 export async function GET(request: Request) {
   const { searchParams } = new URL(request.url)
@@ -59,14 +57,8 @@ export async function GET(request: Request) {
     )
   }
 
-  const schemaContent = await fs.readFile(schemaPath, "utf-8")
-  const schema = parseDocument(schemaContent).toJS() as SchemaObject
-
-  // resolve references in schema
-  const dereferencedDocument = await dereference({
-    basePath: baseSchemasPath,
-    schemas: [schema],
-  })
+  const { dereferencedDocument, originalSchema: schema } =
+    await getSchemaContent(schemaPath, baseSchemasPath)
 
   return NextResponse.json(
     {

www/apps/api-reference/app/store/page.tsx

@@ -3,22 +3,35 @@ import StoreContent from "../_mdx/store.mdx"
 import Tags from "@/components/Tags"
 import PageTitleProvider from "@/providers/page-title"
 import { H1 } from "docs-ui"
+import { getBaseSpecs } from "../../lib"
+import BaseSpecsProvider from "../../providers/base-specs"
+import clsx from "clsx"
+
+const StorePage = async () => {
+  const data = await getBaseSpecs("store")
 
-const ReferencePage = async () => {
   return (
-    <AreaProvider area={"store"}>
-      <PageTitleProvider>
-        <H1 className="!h2-docs scroll-m-56 lg:pl-4" id="introduction">
-          Medusa V2 Store API Reference
-        </H1>
-        <StoreContent />
-        <Tags />
-      </PageTitleProvider>
-    </AreaProvider>
+    <BaseSpecsProvider baseSpecs={data}>
+      <AreaProvider area={"store"}>
+        <PageTitleProvider>
+          <H1
+            className={clsx(
+              "!h2-docs lg:pl-4",
+              "scroll-m-[184px] lg:scroll-m-[264px]"
+            )}
+            id="introduction"
+          >
+            Medusa V2 Store API Reference
+          </H1>
+          <StoreContent />
+          <Tags tags={data?.tags} />
+        </PageTitleProvider>
+      </AreaProvider>
+    </BaseSpecsProvider>
   )
 }
 
-export default ReferencePage
+export default StorePage
 
 export function generateMetadata() {
   return {