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() を渡します。これにより、ファイルを書き出さずにページを生成できます。

import { getCollection } from 'astro:content';
import { loader } from 'fumadocs-core/source';
import { toFumadocsSource } from '@fumadocs/astro/source';
import { asyncapi } from '@/lib/asyncapi'; 

export const source = loader(
  {
    docs: toFumadocsSource(await getCollection('docs'), await getCollection('meta')),
    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')}`;
    }

    // 以下は既存の処理...
  },
});

AsyncAPI ページは専用のアイランドでレンダリングします。このアイランドでは、<AsyncAPIPage /> を Docs レイアウトでラップします。

---
import type { GetStaticPaths, InferGetStaticPropsType } from 'astro';
import Layout from '@/layouts/Layout.astro';
import { Docs } from '@/components/docs';
import { AsyncAPIDocs } from '@/components/asyncapi-docs'; 
import { source } from '@/lib/source';

export const prerender = true;

export const getStaticPaths = (() => {
  return source.getPages().map((page) => ({
    params: { slug: decodeURI(page.slugs.join('/')) || undefined },
    props: { page },
  }));
}) satisfies GetStaticPaths;

type Props = InferGetStaticPropsType<typeof getStaticPaths>;

const { page } = Astro.props;
const pageTree = await source.serializePageTree(source.getPageTree());
---

{/* [!code ++:13] */}
{page.type === 'asyncapi' && (
  <Layout title={page.data.title ?? 'My App'}>
    <AsyncAPIDocs
      client:load
      pathname={Astro.url.pathname}
      params={Astro.params}
      tree={pageTree}
      title={page.data.title}
      props={page.data.getAsyncAPIPageProps()}
    />
  </Layout>
)}

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 のサンプルをご覧ください。