跳至內容
Fumadocs

createOpenAPI()

OpenAPI 伺服器實例。

OpenAPI 伺服器

Fumadocs OpenAPI 的主要設定。

請勿在瀏覽器環境中引用此設定。

input

要讀取的 OpenAPI schema。

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

只有列在此處的 schema 才能載入;傳給 getSchema() 或由頁面預先載入的其他 ID 都會拋出錯誤。

請勿將不受信任的 schema 傳給 input,因為其中的 $ref 能讀取本機檔案並請求任意 URL,私有主機也包含在內。

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

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

只載入一次文件

頁面會透過 props 接收完整的文件,因此每次載入頁面、切換頁面或預先擷取時,都會重新傳送整份文件。若文件較大,建議不要將它放進 props:

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

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

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

components/api-page.tsx
'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 請求,以及裝置授權流程 (device flow) 。

代理伺服器為公開存取,不需經過驗證。它會轉送請求的標頭與 body,包括 Authorization。請使用 allowedOrigins 與 filterRequest 限制其存取。

設定

互動測試區會以 POST 將請求傳送至代理伺服器,並將該 operation 的 HTTP 方法帶在 URL 中。請為此建立路由處理常式:

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

const proxy = openapi.createProxy();

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

接著在 createOpenAPI() 中設定代理伺服器的 URL:

lib/openapi.ts
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'],
});

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

拒絕私有網路的請求需要 Node.js 或 Deno。若使用其他執行階段 (例如 Bun) ,請指定 allowedOrigins。

您可以使用 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) :

components/api-page.tsx
export const OpenAPIPage = createOpenAPIPage({
  oauthRedirectUrl: '/api/oauth', 
});

內容安全政策(Content Security Policy)

處理常式會透過自身路由提供的指令碼,將使用者導回原頁面。若該路由受到 Content Security Policy 規範,該政策必須允許 'self' 指令碼。含有 'strict-dynamic' 的政策會忽略 'self',因此請改為將該路由排除在這類政策之外。

靜態網站

在靜態網站上,該路由會預先算繪為檔案。請傳入 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) 必須允許內嵌指令碼。

How is this guide?