# Fumadocs (Framework Mode, React Router): AsyncAPI
URL: /zh-TW/docs/react-router/integrations/asyncapi
Source: https://raw.githubusercontent.com/fuma-nama/fumadocs/refs/heads/main/apps/docs/content/docs/(framework)/[framework]/integrations/asyncapi/index.zh-TW.mdx

根據 AsyncAPI schema 產生文件。

## 設定 [#setup]

請安裝所需的套件。

```npm
npm i @fumadocs/asyncapi shiki
```

### 產生樣式 [#generate-styles]

請加入下面這一行：

```css title="Tailwind CSS"
@import 'tailwindcss';
@import 'fumadocs-ui/css/neutral.css';
@import 'fumadocs-ui/css/preset.css';
/* [!code ++] */
@import '@fumadocs/asyncapi/css/preset.css';
```

### 設定外掛 [#configure-plugin]

建立 AsyncAPI 伺服器實例及 `<AsyncAPIPage />` 元件。

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

// 注意：這是伺服器端 API
export const asyncapi = createAsyncAPI({
  // AsyncAPI schema，也可以改為提供外部 URL。
  input: ['./asyncapi.yaml'],
});
```

```tsx tab="components/api-page.tsx"
'use client';
import { createAsyncAPIPage } from '@fumadocs/asyncapi/ui';

export const AsyncAPIPage = createAsyncAPIPage();
```

可用選項請參閱 [`createAsyncAPI()`](/docs/react-router/integrations/asyncapi/server) 與 [`createAsyncAPIPage()`](/docs/react-router/integrations/asyncapi/api-page)。

### 產生頁面 [#generate-pages]

將 `staticSource()` 傳入您的 [`loader()`](/docs/headless/source-api/source)，即可產生頁面，而不必實際寫入檔案。

由於 `staticSource()` 會讀取檔案，`source.ts` 將變成僅限伺服器端使用。請將 `docs` 移至 `collections.ts`，讓用戶端程式碼可以匯入。

```ts tab="app/lib/source.ts"
import { loader } from 'fumadocs-core/source';
import { defineDocs } from 'fumadocs-mdx/macro'; // [!code --]
// [!code ++:2]
import { docs } from '@/lib/collections';
import { asyncapi } from '@/lib/asyncapi';

// [!code --:6]
export const docs = defineDocs({
  dir: 'content/docs',
  docs: {
    async: true,
  },
});

// 由於 `staticSource()` 會讀取檔案，現在僅限伺服器端使用 [!code ++]
export const source = loader(
  // [!code ++:6]
  {
    docs: docs.toFumadocsSource(),
    asyncapi: await asyncapi.staticSource({
      baseDir: 'asyncapi',
    }),
  },
  {
    baseUrl: '/docs',
    // [!code ++:2] 選用：在頁面樹的每個頁面項目中加入訊息的方向
    plugins: [asyncapi.loaderPlugin()],
  },
);
```

```ts tab="app/lib/collections.ts"
import { defineDocs } from 'fumadocs-mdx/macro';

export const docs = defineDocs({
  dir: 'content/docs',
  docs: {
    async: true,
  },
});
```

`staticSource()` 預設會為每個 operation 產生一個頁面。如需自訂，請參閱[產生頁面](/docs/react-router/integrations/asyncapi/generate-files)。

**`source` 的頁面現在分為 `docs` 與 `asyncapi` 兩種類型。** 請更新所有使用 `source` 的地方，例如回傳文字給 LLM 的地方：

```ts
import { llms } from 'fumadocs-core/source';
import { source } from '@/lib/source';

export const docsLlms = llms(source, {
  renderPage: async (page) => {
    // [!code ++:3]
    if (page.type === 'asyncapi') {
      return `# ${page.data.title}\n\n${await page.data.getText('processed')}`;
    }

    // 以下為您原本的流程……
  },
});
```

在您的文件頁面中，使用 `<AsyncAPIPage />` 算繪 AsyncAPI 頁面：

```tsx title="app/routes/docs.tsx"
import { docs, source } from '@/lib/source'; // [!code --]
// [!code ++:3]
import { docs } from '@/lib/collections';
import { source } from '@/lib/source';
import { AsyncAPIPage } from '@/components/api-page';

export async function loader({ params }: Route.LoaderArgs) {
  const slugs = params['*'].split('/').filter((v) => v.length > 0);
  const page = source.getPage(slugs);
  if (!page) throw new Response('Not found', { status: 404 });

  // [!code ++:9]
  const pageTree = await source.serializePageTree(source.getPageTree());
  if (page.type === 'asyncapi') {
    return {
      type: 'asyncapi' as const,
      title: page.data.title,
      props: page.data.getAsyncAPIPageProps(),
      pageTree,
    };
  }

  return { type: 'docs' as const, path: page.path, pageTree }; // [!code highlight]
}

export default function Page({ loaderData }: Route.ComponentProps) {
  const data = useFumadocsLoader(loaderData);

  return (
    <DocsLayout {...baseOptions()} tree={data.pageTree}>
      {/* [!code ++:8] */}
      {data.type === 'asyncapi' && (
        <DocsPage full>
          <DocsTitle>{data.title}</DocsTitle>
          <DocsBody>
            <AsyncAPIPage {...data.props} />
          </DocsBody>
        </DocsPage>
      )}
      {/* [!code highlight] */}
      {data.type === 'docs' && <Content path={data.path} />}
    </DocsLayout>
  );
}
```

<Callout type="warn" title="請確認已完成遷移！">
繼續之前，請先執行型別檢查：

```npm
npm run types:check
```
</Callout>

若想改為將 MDX 檔案寫入內容目錄，請參閱 [MDX 檔案](/docs/react-router/integrations/asyncapi/generate-files#mdx-files)。

## 功能 [#features]

官方 AsyncAPI 整合支援 AsyncAPI 3：

* 向讀者標示訊息的方向，以及 operation 的伺服器與頻道位址
* 訊息及其酬載與標頭 schema，包括 Avro、Protobuf 與 RAML schema
* 訊息範例，可取自文件或由 schema 產生
* 請求與回覆、關聯 ID (correlation ID) 
* 安全性方案，包括 OAuth 2.0 流程與 SASL 機制
* 針對所選伺服器，呈現 bindings 中的協定細節
* 支援 WebSocket、Server-Sent Events 與自訂傳輸層的互動測試區，可傳送文字與二進位訊息
* JavaScript 與 Python 的程式碼範例，涵蓋 WebSocket、MQTT、Kafka、AMQP 與 NATS
* 酬載與標頭的 TypeScript 型別定義
* 供 LLM 使用的頁面 Markdown
* 特徵 (traits) 

AsyncAPI 2 文件可使用 `npx @asyncapi/cli convert` 進行轉換。

### 示範 [#demo]

請參閱 [AsyncAPI 範例](/docs/asyncapi)。