Core & OpenAPI: Improve Fumadocs OpenAPI support (TOC & Structured Data plugins)

fuma-nama · fuma-nama · commit 61b91fa2a093 · 2024-08-13T18:06:51.000+08:00
diff --git a/.changeset/honest-readers-guess.md b/.changeset/honest-readers-guess.md
@@ -0,0 +1,7 @@
+---
+'fumadocs-openapi': patch
+'fumadocs-core': patch
+'fumadocs-mdx': patch
+---
+
+Improve Fumadocs OpenAPI support
diff --git a/examples/openapi/content/docs/index.mdx b/examples/openapi/content/docs/index.mdx
@@ -34,5 +34,3 @@ curl -XPOST "https://api.unkey.dev/v1/keys.createKey" \
   -H "Content-Type: application/json" \
   -d '{"apiId": "api_123", "name": "My Key"}'
 ```
-
-![img](https://miro.medium.com/v2/resize:fit:4800/format:webp/1*qHtOm0c0IXsefOd2W7VECg.png)
diff --git a/packages/core/src/mdx-plugins/remark-heading.ts b/packages/core/src/mdx-plugins/remark-heading.ts
@@ -40,6 +40,19 @@ export function remarkHeading({
     const toc: TOCItemType[] = [];
     slugger.reset();
 
+    // Fumadocs OpenAPI Generated TOC
+    if (file.data.frontmatter) {
+      const frontmatter = file.data.frontmatter as {
+        _openapi?: {
+          toc?: TOCItemType[];
+        };
+      };
+
+      if (frontmatter._openapi?.toc) {
+        toc.push(...frontmatter._openapi.toc);
+      }
+    }
+
     visit(root, 'heading', (heading) => {
       heading.data ||= {};
       heading.data.hProperties ||= {};
diff --git a/packages/core/src/mdx-plugins/remark-structure.ts b/packages/core/src/mdx-plugins/remark-structure.ts
@@ -45,6 +45,20 @@ export function remarkStructure({
     const data: StructuredData = { contents: [], headings: [] };
     let lastHeading: string | undefined = '';
 
+    // Fumadocs OpenAPI Generated Structured Data
+    if (file.data.frontmatter) {
+      const frontmatter = file.data.frontmatter as {
+        _openapi?: {
+          structuredData?: StructuredData;
+        };
+      };
+
+      if (frontmatter._openapi?.structuredData) {
+        data.headings.push(...frontmatter._openapi.structuredData.headings);
+        data.contents.push(...frontmatter._openapi.structuredData.contents);
+      }
+    }
+
     visit(node, types, (element) => {
       if (element.type === 'root') return;
       const content = flattenNode(element).trim();
diff --git a/packages/openapi/src/server/source-api.tsx b/packages/openapi/src/server/source-api.tsx
@@ -18,8 +18,6 @@ export const attachFile: BuildPageTreeOptions['attachFile'] = (node, file) => {
     };
 
     method = meta.method;
-  } else if ('method' in data && typeof data.method === 'string') {
-    method = data.method;
   }
 
   if (method) {
diff --git a/packages/openapi/src/utils/generate-document.ts b/packages/openapi/src/utils/generate-document.ts
@@ -64,7 +64,7 @@ export function generateDocument(
     out.push(imports);
   }
 
-  out.push(pageContent(data, options.page));
+  out.push(pageContent(options.page));
 
   return out.join('\n\n');
 }
@@ -108,24 +108,6 @@ function generateStaticData(
   return { toc, structuredData };
 }
 
-function pageContent(data: StaticData, props: ApiPageProps): string {
-  // modify toc and structured data if possible
-  // it may not be compatible with other content sources except Fumadocs MDX
-  // TODO: Maybe add to frontmatter and let developers to handle them?
-  return `<APIPage document={${JSON.stringify(props.document)}} operations={${JSON.stringify(props.operations)}} hasHead={${JSON.stringify(props.hasHead)}} />
-
-export function startup() {
-    if (typeof toc !== 'undefined') {
-        // toc might be immutable
-        while (toc.length > 0) toc.pop()
-        toc.push(...${JSON.stringify(data.toc)})
-    }
-    
-    if (typeof structuredData !== 'undefined') {
-        structuredData.headings = ${JSON.stringify(data.structuredData.headings)}
-        structuredData.contents = ${JSON.stringify(data.structuredData.contents)}
-    }
-}
-
-{startup()}`;
+function pageContent(props: ApiPageProps): string {
+  return `<APIPage document={${JSON.stringify(props.document)}} operations={${JSON.stringify(props.operations)}} hasHead={${JSON.stringify(props.hasHead)}} />`;
 }
diff --git a/packages/openapi/test/out/museum/events.mdx b/packages/openapi/test/out/museum/events.mdx
@@ -46,19 +46,4 @@ _openapi:
         heading: delete-special-event
 ---
 
-<APIPage document={"./fixtures/museum.yaml"} operations={[{"method":"get","path":"/special-events"},{"method":"post","path":"/special-events"},{"method":"get","path":"/special-events/{eventId}"},{"method":"patch","path":"/special-events/{eventId}"},{"method":"delete","path":"/special-events/{eventId}"}]} hasHead={true} />
-
-export function startup() {
-    if (typeof toc !== 'undefined') {
-        // toc might be immutable
-        while (toc.length > 0) toc.pop()
-        toc.push(...[{"depth":2,"title":"List special events","url":"#list-special-events"},{"depth":2,"title":"Create special events","url":"#create-special-events"},{"depth":2,"title":"Get special event","url":"#get-special-event"},{"depth":2,"title":"Update special event","url":"#update-special-event"},{"depth":2,"title":"Delete special event","url":"#delete-special-event"}])
-    }
-    
-    if (typeof structuredData !== 'undefined') {
-        structuredData.headings = [{"content":"List special events","id":"list-special-events"},{"content":"Create special events","id":"create-special-events"},{"content":"Get special event","id":"get-special-event"},{"content":"Update special event","id":"update-special-event"},{"content":"Delete special event","id":"delete-special-event"}]
-        structuredData.contents = [{"content":"Return a list of upcoming special events at the museum.","heading":"list-special-events"},{"content":"Creates a new special event for the museum.","heading":"create-special-events"},{"content":"Get details about a special event.","heading":"get-special-event"},{"content":"Update the details of a special event","heading":"update-special-event"},{"content":"Delete a special event from the collection. Allows museum to cancel planned events.","heading":"delete-special-event"}]
-    }
-}
-
-{startup()}
+<APIPage document={"./fixtures/museum.yaml"} operations={[{"method":"get","path":"/special-events"},{"method":"post","path":"/special-events"},{"method":"get","path":"/special-events/{eventId}"},{"method":"patch","path":"/special-events/{eventId}"},{"method":"delete","path":"/special-events/{eventId}"}]} hasHead={true} />
diff --git a/packages/openapi/test/out/museum/operations.mdx b/packages/openapi/test/out/museum/operations.mdx
@@ -16,19 +16,4 @@ _openapi:
         heading: get-museum-hours
 ---
 
-<APIPage document={"./fixtures/museum.yaml"} operations={[{"method":"get","path":"/museum-hours"}]} hasHead={true} />
-
-export function startup() {
-    if (typeof toc !== 'undefined') {
-        // toc might be immutable
-        while (toc.length > 0) toc.pop()
-        toc.push(...[{"depth":2,"title":"Get museum hours","url":"#get-museum-hours"}])
-    }
-    
-    if (typeof structuredData !== 'undefined') {
-        structuredData.headings = [{"content":"Get museum hours","id":"get-museum-hours"}]
-        structuredData.contents = [{"content":"Get upcoming museum operating hours","heading":"get-museum-hours"}]
-    }
-}
-
-{startup()}
+<APIPage document={"./fixtures/museum.yaml"} operations={[{"method":"get","path":"/museum-hours"}]} hasHead={true} />
diff --git a/packages/openapi/test/out/museum/tickets.mdx b/packages/openapi/test/out/museum/tickets.mdx
@@ -25,19 +25,4 @@ _openapi:
         heading: get-ticket-qr-code
 ---
 
-<APIPage document={"./fixtures/museum.yaml"} operations={[{"method":"post","path":"/tickets"},{"method":"get","path":"/tickets/{ticketId}/qr"}]} hasHead={true} />
-
-export function startup() {
-    if (typeof toc !== 'undefined') {
-        // toc might be immutable
-        while (toc.length > 0) toc.pop()
-        toc.push(...[{"depth":2,"title":"Buy museum tickets","url":"#buy-museum-tickets"},{"depth":2,"title":"Get ticket QR code","url":"#get-ticket-qr-code"}])
-    }
-    
-    if (typeof structuredData !== 'undefined') {
-        structuredData.headings = [{"content":"Buy museum tickets","id":"buy-museum-tickets"},{"content":"Get ticket QR code","id":"get-ticket-qr-code"}]
-        structuredData.contents = [{"content":"Purchase museum tickets for general entry or special events.","heading":"buy-museum-tickets"},{"content":"Return an image of your ticket with scannable QR code. Used for event entry.","heading":"get-ticket-qr-code"}]
-    }
-}
-
-{startup()}
+<APIPage document={"./fixtures/museum.yaml"} operations={[{"method":"post","path":"/tickets"},{"method":"get","path":"/tickets/{ticketId}/qr"}]} hasHead={true} />
diff --git a/packages/openapi/test/out/petstore.mdx b/packages/openapi/test/out/petstore.mdx
@@ -23,19 +23,4 @@ _openapi:
     contents: []
 ---
 
-<APIPage document={"./fixtures/petstore.yaml"} operations={[{"method":"get","path":"/pets"},{"method":"post","path":"/pets"},{"method":"get","path":"/pets/{petId}"}]} hasHead={true} />
-
-export function startup() {
-    if (typeof toc !== 'undefined') {
-        // toc might be immutable
-        while (toc.length > 0) toc.pop()
-        toc.push(...[{"depth":2,"title":"List all pets","url":"#list-all-pets"},{"depth":2,"title":"Create a pet","url":"#create-a-pet"},{"depth":2,"title":"Info for a specific pet","url":"#info-for-a-specific-pet"}])
-    }
-    
-    if (typeof structuredData !== 'undefined') {
-        structuredData.headings = [{"content":"List all pets","id":"list-all-pets"},{"content":"Create a pet","id":"create-a-pet"},{"content":"Info for a specific pet","id":"info-for-a-specific-pet"}]
-        structuredData.contents = []
-    }
-}
-
-{startup()}
+<APIPage document={"./fixtures/petstore.yaml"} operations={[{"method":"get","path":"/pets"},{"method":"post","path":"/pets"},{"method":"get","path":"/pets/{petId}"}]} hasHead={true} />
diff --git a/packages/openapi/test/out/unkey/apis.mdx b/packages/openapi/test/out/unkey/apis.mdx
@@ -28,19 +28,4 @@ _openapi:
     contents: []
 ---
 
-<APIPage document={"./fixtures/unkey.json"} operations={[{"method":"get","path":"/v1/apis.getApi"},{"method":"post","path":"/v1/apis.createApi"},{"method":"get","path":"/v1/apis.listKeys"},{"method":"post","path":"/v1/apis.deleteApi"}]} hasHead={true} />
-
-export function startup() {
-    if (typeof toc !== 'undefined') {
-        // toc might be immutable
-        while (toc.length > 0) toc.pop()
-        toc.push(...[{"depth":2,"title":"Get Api","url":"#get-api"},{"depth":2,"title":"Create Api","url":"#create-api"},{"depth":2,"title":"List Keys","url":"#list-keys"},{"depth":2,"title":"Delete Api","url":"#delete-api"}])
-    }
-    
-    if (typeof structuredData !== 'undefined') {
-        structuredData.headings = [{"content":"Get Api","id":"get-api"},{"content":"Create Api","id":"create-api"},{"content":"List Keys","id":"list-keys"},{"content":"Delete Api","id":"delete-api"}]
-        structuredData.contents = []
-    }
-}
-
-{startup()}
+<APIPage document={"./fixtures/unkey.json"} operations={[{"method":"get","path":"/v1/apis.getApi"},{"method":"post","path":"/v1/apis.createApi"},{"method":"get","path":"/v1/apis.listKeys"},{"method":"post","path":"/v1/apis.deleteApi"}]} hasHead={true} />
diff --git a/packages/openapi/test/out/unkey/keys.mdx b/packages/openapi/test/out/unkey/keys.mdx
@@ -43,19 +43,4 @@ _openapi:
     contents: []
 ---
 
-<APIPage document={"./fixtures/unkey.json"} operations={[{"method":"get","path":"/v1/keys.getKey"},{"method":"post","path":"/v1/keys.deleteKey"},{"method":"post","path":"/v1/keys.createKey"},{"method":"post","path":"/v1/keys.verifyKey"},{"method":"post","path":"/v1/keys.updateKey"},{"method":"post","path":"/v1/keys.updateRemaining"},{"method":"get","path":"/v1/keys.getVerifications"}]} hasHead={true} />
-
-export function startup() {
-    if (typeof toc !== 'undefined') {
-        // toc might be immutable
-        while (toc.length > 0) toc.pop()
-        toc.push(...[{"depth":2,"title":"Get Key","url":"#get-key"},{"depth":2,"title":"Delete Key","url":"#delete-key"},{"depth":2,"title":"Create Key","url":"#create-key"},{"depth":2,"title":"Verify Key","url":"#verify-key"},{"depth":2,"title":"Update Key","url":"#update-key"},{"depth":2,"title":"Update Remaining","url":"#update-remaining"},{"depth":2,"title":"Get Verifications","url":"#get-verifications"}])
-    }
-    
-    if (typeof structuredData !== 'undefined') {
-        structuredData.headings = [{"content":"Get Key","id":"get-key"},{"content":"Delete Key","id":"delete-key"},{"content":"Create Key","id":"create-key"},{"content":"Verify Key","id":"verify-key"},{"content":"Update Key","id":"update-key"},{"content":"Update Remaining","id":"update-remaining"},{"content":"Get Verifications","id":"get-verifications"}]
-        structuredData.contents = []
-    }
-}
-
-{startup()}
+<APIPage document={"./fixtures/unkey.json"} operations={[{"method":"get","path":"/v1/keys.getKey"},{"method":"post","path":"/v1/keys.deleteKey"},{"method":"post","path":"/v1/keys.createKey"},{"method":"post","path":"/v1/keys.verifyKey"},{"method":"post","path":"/v1/keys.updateKey"},{"method":"post","path":"/v1/keys.updateRemaining"},{"method":"get","path":"/v1/keys.getVerifications"}]} hasHead={true} />
diff --git a/packages/openapi/test/out/unkey/liveness.mdx b/packages/openapi/test/out/unkey/liveness.mdx
@@ -13,19 +13,4 @@ _openapi:
     contents: []
 ---
 
-<APIPage document={"./fixtures/unkey.json"} operations={[{"method":"get","path":"/v1/liveness"}]} hasHead={true} />
-
-export function startup() {
-    if (typeof toc !== 'undefined') {
-        // toc might be immutable
-        while (toc.length > 0) toc.pop()
-        toc.push(...[{"depth":2,"title":"Check Liveness","url":"#check-liveness"}])
-    }
-    
-    if (typeof structuredData !== 'undefined') {
-        structuredData.headings = [{"content":"Check Liveness","id":"check-liveness"}]
-        structuredData.contents = []
-    }
-}
-
-{startup()}
+<APIPage document={"./fixtures/unkey.json"} operations={[{"method":"get","path":"/v1/liveness"}]} hasHead={true} />
diff --git a/pnpm-lock.yaml b/pnpm-lock.yaml

Original file line number	Diff line number	Diff line change
`@@ -18,8 +18,6 @@ export const attachFile: BuildPageTreeOptions['attachFile'] = (node, file) => {`
`18`	`18`	`};`
`19`	`19`
`20`	`20`	`method = meta.method;`
`21`		`- } else if ('method' in data && typeof data.method === 'string') {`
`22`		`- method = data.method;`
`23`	`21`	`}`
`24`	`22`
`25`	`23`	`if (method) {`