# Fumadocs (Framework Mode, TanStack Start): createAsyncAPI()
URL: /zh-TW/docs/tanstack-start/integrations/asyncapi/server
Source: https://raw.githubusercontent.com/fuma-nama/fumadocs/refs/heads/main/apps/docs/content/docs/(framework)/[framework]/integrations/asyncapi/server.zh-TW.mdx

AsyncAPI 伺服器實例。

## AsyncAPI 伺服器 [#asyncapi-server]

Fumadocs AsyncAPI 的主要設定。

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

### `input` [#input]

要讀取的 AsyncAPI schema。

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

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

<Callout type="warn">
請勿將不受信任的 schema 傳給 `input`，因為其中的 `$ref` 能讀取本機檔案並擷取任意 URL，連私有主機也不例外。
</Callout>

```ts tab="Basic"
import { createAsyncAPI } from '@fumadocs/asyncapi/server';

export const asyncapi = createAsyncAPI({
  input: ['./streetlights.yaml'],
});
```

```ts tab="Functions"
import { createAsyncAPI } from '@fumadocs/asyncapi/server';

export const asyncapi = createAsyncAPI({
  input: {
    // [id]：下載後的 AsyncAPI schema
    galaxy: async () => {
      const res = await fetch('https://example.com/asyncapi.yaml');
      return res.text();
    },
  },
});
```

### `disableCache` [#disablecache]

停用已載入 schema 的快取。適合在開發階段 schema 頻繁變動時使用。

```ts
import { createAsyncAPI } from '@fumadocs/asyncapi/server';

export const asyncapi = createAsyncAPI({
  input: ['./asyncapi.yaml'],
  disableCache: true,
});
```

## 只載入一次文件 [#loading-documents-once]

頁面會透過 props 接收完整的文件，因此每次載入頁面、導覽或預先擷取時，都會再傳送一次文件。若文件較大，建議不要透過 props 傳遞：

```ts title="lib/asyncapi.ts"
import { createAsyncAPI } from '@fumadocs/asyncapi/server';

export const asyncapi = createAsyncAPI({
  // ID 最終會出現在 URL 中，請確保可安全用於 URL
  input: { streetlights: './streetlights.yaml' },
  includeDocument: false, // [!code ++]
});
```

TanStack Start 的路由載入器會同時在伺服器與瀏覽器上執行，因此您的文件路由不需要 `loadDocument` 也能載入文件。只有在瀏覽器尚未取得文件時，才需要呼叫 server function：

```tsx title="src/routes/docs/$.tsx"
import { createServerFn } from '@tanstack/react-start';
import type { AsyncAPI } from '@fumadocs/asyncapi';
import { asyncapi } from '@/lib/asyncapi';

// 瀏覽器已載入的文件
const documents = new Map<string, AsyncAPI.AsyncAPIObject>();

const getDocument = createServerFn({ method: 'GET' })
  .validator((id: string) => id)
  .handler(async ({ data: id }) => (await asyncapi.getSchema(id)).bundled);

export const Route = createFileRoute('/docs/$')({
  component: Page,
  loader: async ({ params }) => {
    const data = await serverLoader({ data: params._splat?.split('/') ?? [] });
    if (data.type === 'asyncapi') {
      const { document: id, payload } = data.props;
      payload.bundled = documents.get(id) ?? (await getDocument({ data: id }));
    }
    return data;
  },
});

function Page() {
  const page = useFumadocsLoader(Route.useLoaderData());
  // 第一個頁面的文件也要記錄
  if (page.type === 'asyncapi' && typeof window !== 'undefined')
    documents.set(page.props.document, page.props.payload.bundled!);
  // ...
}
```

* 若使用產生的 MDX 檔案，請改將文件放入 `preloaded.docs`。
* 瀏覽器會保留每份文件，直到頁面重新載入為止。使用 [`disableCache`](#disablecache) 時，請保持開啟 `includeDocument`。