AsyncAPI
AsyncAPI スキーマからドキュメントを生成します。
セットアップ
必要なパッケージをインストールします。
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 スキーマ。外部 URL を指定することもできます。
input: ['./asyncapi.yaml'],
});各オプションの詳細については、createAsyncAPI() と createAsyncAPIPage() を参照してください。
ページを生成する
loader() に staticSource() を渡します。これにより、ファイルを書き出さずにページを生成できます。
staticSource() はファイルを読み込むため、source.ts はサーバー専用になります。クライアントのコードから import できるよう、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() は、デフォルトでオペレーションごとに1ページを生成します。カスタマイズ方法についてはページの生成を参照してください。
source のページは、docs と asyncapi の2種類になりました。 LLM 向けのテキストを返す箇所など、source を使用しているすべての箇所を更新してください。
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')}`;
}
// 以下は既存の処理...
},
});docs ページで <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:checkMDX ファイルをコンテンツディレクトリに書き出したい場合は、MDX ファイルを参照してください。
機能
公式の AsyncAPI インテグレーションは AsyncAPI 3 をサポートしており、以下を提供します。
- 読者から見たメッセージの方向、オペレーションのサーバーとチャンネルのアドレス
- メッセージとそのペイロードおよびヘッダーのスキーマ(Avro、Protobuf、RAML のスキーマを含む)
- メッセージの例(ドキュメントに記載されたもの、またはスキーマから生成したもの)
- リクエストと応答、相関 ID
- セキュリティスキーム(OAuth 2.0 フローや SASL メカニズムを含む)
- 選択したサーバーについて、バインディングから取得したプロトコルの詳細
- WebSocket、Server-Sent Events、カスタムトランスポートに対応したプレイグラウンド(テキストメッセージとバイナリメッセージの両方に対応)
- WebSocket、MQTT、Kafka、AMQP、NATS 向けの JavaScript と Python のコードサンプル
- ペイロードとヘッダーの TypeScript 型定義
- LLM 向けのページの Markdown
- トレイト
AsyncAPI 2 のドキュメントは npx @asyncapi/cli convert で変換できます。
デモ
AsyncAPI のサンプルをご覧ください。
How is this guide?
最終更新日
General Translation
Ferry Health
assistant-ui
Inkeep