createOpenAPI()

OpenAPI 伺服器複製錨點連結

Fumadocs OpenAPI 的主要設定。

input複製錨點連結

要讀取的 OpenAPI schema。

• 檔案路徑
• 外部 URL
• 函式 (見下文)

只有列在此處的 schema 才能載入；若傳入 getSchema() 或由頁面預先載入的是其他 ID，則會拋出錯誤。

import { createOpenAPI } from 'fumadocs-openapi/server';

export const openapi = createOpenAPI({
  input: ['./unkey.json'],
});

只載入一次文件複製錨點連結

頁面會透過 props 接收完整的文件，因此每次載入頁面、切換頁面與預先擷取時，都會重新傳送整份文件。若文件較大，建議將其排除：

import { createOpenAPI } from 'fumadocs-openapi/server';

export const openapi = createOpenAPI({
  // ID 最後會出現在 URL 中，請確保可安全用於 URL
  input: { museum: './museum.yaml' },
  includeDocument: false, 
});

傳入 loadDocument，即可讓每份文件在每個瀏覽器工作階段中只載入一次。它在伺服器端算繪時也會執行：

'use client';
import { preload } from 'react-dom';
import { createOpenAPIPage } from 'fumadocs-openapi/ui';

export const OpenAPIPage = createOpenAPIPage({
  async loadDocument(id) {
    if (import.meta.env.SSR) {
      // 瀏覽器會在載入頁面的同時開始下載它
      preload(`/api/openapi/${id}`, { as: 'fetch', crossOrigin: 'anonymous' });
      const { openapi } = await import('@/lib/openapi');
      return (await openapi.getSchema(id)).bundled;
    }
    return (await fetch(`/api/openapi/${id}`)).json();
  },
});

透過路由將文件提供給瀏覽器：

import type { Route } from './+types/openapi';
import { openapi } from '@/lib/openapi';

export async function loader({ params }: Route.LoaderArgs) {
  return Response.json((await openapi.getSchema(params.id)).bundled);
}

• loadDocument 也適用於產生的 MDX 檔案。
• 若使用由 Fumadocs CLI 安裝的 UI，請將 loadDocument 傳入 createOpenAPIRenderer()。
• 瀏覽器會保留每份文件，直到重新載入頁面為止。使用 disableCache 時，請保持啟用 includeDocument。

建立代理伺服器複製錨點連結

代理伺服器傳送 HTTP 請求時不受瀏覽器的 CORS 限制。API 互動測試區會在以下情況使用它：

• 請求未透過 CORS 允許您的來源的 API 端點。
• 機密用戶端 (具有 client secret) 的 OAuth 請求，以及裝置授權流程。

設定複製錨點連結

為代理伺服器建立路由處理常式：

import type { Route } from './+types/proxy';
import { openapi } from '@/lib/openapi';

const proxy = openapi.createProxy();

export const loader = ({ request }: Route.LoaderArgs) => proxy.handle(request);
export const action = ({ request }: Route.ActionArgs) => proxy.handle(request);

接著在 createOpenAPI() 中設定其 URL：

import { createOpenAPI } from 'fumadocs-openapi/server';

export const openapi = createOpenAPI({
  proxyUrl: '/api/proxy', 
});

允許的來源複製錨點連結

代理伺服器預設會接受任何公開來源，並拒絕私有網路上的主機 (例如 localhost) ，也不會轉送您網站的 Cookie。 若要限制存取範圍，或要代理私有 API，請在代理伺服器路由中列出允許的來源：

openapi.createProxy({
  // 字串或正規表示式
  allowedOrigins: ['https://api.example.com', 'http://localhost:8080'],
});

重新導向也會依照相同的規則進行檢查。

您可以使用 filterRequest 拒絕請求，例如只允許讀取操作：

openapi.createProxy({
  // 回傳 false 的代理請求會被拒絕
  filterRequest: (request) => request.method === 'GET',
});

OAuth 重新導向複製錨點連結

OAuth 提供者只接受已註冊的重新導向 URI，但 API 互動測試區預設會重新導向至目前頁面。 請建立一個路由處理常式，作為所有頁面共用的重新導向 URI。它會將使用者導回發起流程的頁面。

import type { Route } from './+types/oauth';
import { openapi } from '@/lib/openapi';

const handler = openapi.createOAuthHandler();

export const loader = ({ request }: Route.LoaderArgs) => handler(request);

請將此路由的 URL 傳入 createOpenAPIPage()，並在 OAuth 提供者中註冊完整 URL (例如 https://docs.example.com/api/oauth) ：

export const OpenAPIPage = createOpenAPIPage({
  oauthRedirectUrl: '/api/oauth', 
});

靜態網站複製錨點連結

在靜態網站中，路由會預先算繪為檔案。請傳入 inline: true 將指令碼內嵌於頁面中，並讓路徑以 .html 結尾，讓靜態主機將該檔案視為 HTML 提供。

import type { Route } from './+types/oauth';
import { openapi } from '@/lib/openapi';

const handler = openapi.createOAuthHandler({ inline: true });

export const loader = ({ request }: Route.LoaderArgs) => handler(request);

請使用 .html URL 作為重新導向 URI，例如 oauthRedirectUrl: '/api/oauth.html'。由於指令碼內嵌於頁面中，套用於此路由的內容安全政策 (Content Security Policy) 必須允許內嵌指令碼。