コンテンツへスキップ
Fumadocs

AsyncAPI

AsyncAPI スキーマからドキュメントを生成します。

セットアップ

必要なパッケージをインストールします。

npm i @fumadocs/asyncapi shiki

スタイルの生成

次の行を追加してください。

Tailwind CSS
@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 ページをレンダリングします。

src/routes/docs/$.tsx
import { docs, source } from '@/lib/source'; 
import { docs } from '@/lib/collections';
import { source } from '@/lib/source';
import { AsyncAPIPage } from '@/components/api-page';
import type { AsyncAPI } from '@fumadocs/asyncapi';

// サーバー関数の戻り値に対する型レベルのチェックでは AsyncAPI ドキュメントを検証できないため、
// シリアライズ可能な型として登録します (`@tanstack/router-core` が解決できない場合はインストールしてください)
declare module '@tanstack/router-core' {
  interface SerializableExtensions {
    asyncapiDocument: AsyncAPI.AsyncAPIObject;
  }
}

export const Route = createFileRoute('/docs/$')({
  component: Page,
  loader: async ({ params }) => {
    const slugs = params._splat?.split('/') ?? [];
    const data = await serverLoader({ data: slugs });
    if (data.type === 'docs') await docs.getPage(data.path)?.preload(); 
    return data;
  },
});

const serverLoader = createServerFn({
  method: 'GET',
})
  .validator((slugs: string[]) => slugs)
  .handler(async ({ data: slugs }) => {
    const page = source.getPage(slugs);
    if (!page) throw notFound();

    const pageTree = await source.serializePageTree(source.getPageTree());
    if (page.type === 'asyncapi') {
      return {
        type: 'asyncapi',
        title: page.data.title,
        props: page.data.getAsyncAPIPageProps(),
        pageTree,
      };
    }

    return { type: 'docs', path: page.path, pageTree }; 
  });

function Page() {
  const data = useFumadocsLoader(Route.useLoaderData());

  return (
    <DocsLayout {...baseOptions()} tree={data.pageTree}>
      {data.type === 'asyncapi' && (
        <DocsPage full>
          <DocsTitle>{data.title}</DocsTitle>
          <DocsBody>
            <AsyncAPIPage {...data.props} />
          </DocsBody>
        </DocsPage>
      )}
      <Suspense>
        {data.type === 'docs' && <Content path={data.path} />}
      </Suspense>
    </DocsLayout>
  );
}

移行が完了していることを確認してください

次に進む前に、型チェックを実行してください。

npm run types:check

MDX ファイルをコンテンツディレクトリに書き出したい場合は、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?

最終更新日

このページの内容

セットアップスタイルの生成プラグインの設定ページを生成する機能デモ
Sponsors
General TranslationGeneral TranslationFerry HealthFerry Healthassistant-uiassistant-uiInkeepInkeep