AsyncAPI
根據 AsyncAPI schema 產生文件。
設定
請安裝所需的套件。
npm i @fumadocs/asyncapi shiki產生樣式
請加入下面這一行：
@import 'tailwindcss';
@import 'fumadocs-ui/css/neutral.css';
@import 'fumadocs-ui/css/preset.css';
@import '@fumadocs/asyncapi/css/preset.css';設定外掛
建立 AsyncAPI 伺服器實例及 <AsyncAPIPage /> 元件。
import { createAsyncAPI } from '@fumadocs/asyncapi/server';
// 注意：這是伺服器端 API
export const asyncapi = createAsyncAPI({
// AsyncAPI schema，也可以改為提供外部 URL。
input: ['./asyncapi.yaml'],
});可用選項請參閱 createAsyncAPI() 與 createAsyncAPIPage()。
產生頁面
將 staticSource() 傳入您的 loader()，即可產生頁面，而不必實際寫入檔案。
由於 staticSource() 會讀取檔案，source.ts 將變成僅限伺服器端使用。請將 docs 移至 collections.ts，讓用戶端程式碼可以匯入。
import { loader } from 'fumadocs-core/source';
import { defineDocs } from 'fumadocs-mdx/macro';
import { docs } from '@/lib/collections';
import { asyncapi } from '@/lib/asyncapi';
export const docs = defineDocs({
dir: 'content/docs',
docs: {
async: true,
},
});
// 由於 `staticSource()` 會讀取檔案，現在僅限伺服器端使用
export const source = loader(
{
docs: docs.toFumadocsSource(),
asyncapi: await asyncapi.staticSource({
baseDir: 'asyncapi',
}),
},
{
baseUrl: '/docs',
// 選用：在頁面樹的每個頁面項目中加入訊息的方向
plugins: [asyncapi.loaderPlugin()],
},
);staticSource() 預設會為每個 operation 產生一個頁面。如需自訂，請參閱產生頁面。
source 的頁面現在分為 docs 與 asyncapi 兩種類型。 請更新所有使用 source 的地方，例如回傳文字給 LLM 的地方：
import { llms } from 'fumadocs-core/source';
import { source } from '@/lib/source';
export const docsLlms = llms(source, {
renderPage: async (page) => {
if (page.type === 'asyncapi') {
return `# ${page.data.title}\n\n${await page.data.getText('processed')}`;
}
// 以下為您原本的流程……
},
});在您的文件頁面中，使用 <AsyncAPIPage /> 算繪 AsyncAPI 頁面：
import { docs, source } from '@/lib/source';
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 });
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 };
}
export default function Page({ loaderData }: Route.ComponentProps) {
const data = useFumadocsLoader(loaderData);
return (
<DocsLayout {...baseOptions()} tree={data.pageTree}>
{data.type === 'asyncapi' && (
<DocsPage full>
<DocsTitle>{data.title}</DocsTitle>
<DocsBody>
<AsyncAPIPage {...data.props} />
</DocsBody>
</DocsPage>
)}
{data.type === 'docs' && <Content path={data.path} />}
</DocsLayout>
);
}請確認已完成遷移！
繼續之前，請先執行型別檢查：
npm run types:check若想改為將 MDX 檔案寫入內容目錄，請參閱 MDX 檔案。
功能
官方 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 進行轉換。
示範
請參閱 AsyncAPI 範例。
How is this guide?
最後更新於
General Translation
Ferry Health
assistant-ui
Inkeep