コンテンツへスキップ
Fumadocs

ページの生成

AsyncAPI スキーマからページを生成します。

staticSource() と dynamicSource() は loader() 用のページを生成し、generateFiles() はそれらを MDX ファイルとしてコンテンツディレクトリに書き出します。いずれも同じオプションを受け付けます。

ページのコンテンツをレンダリングするのは、これまでどおり <AsyncAPIPage /> です。ジェネレーターが行うのは、各ページのオペレーションの構成だけです。

オプション

per

ページの内容の分け方をカスタマイズします。デフォルトは operation です。

オペレーションとは、receiveLightMeasurement:receive のように特定のアクションを持つ AsyncAPI のオペレーションを指します。

モード内容ファイルパス
tag同じタグを持つオペレーション{tag_name}.mdx
file同じスキーマファイル内のオペレーション{file_name}.mdx
operationオペレーションごと{operationId}.mdx
custom後述N/A
import { asyncapi } from '@/lib/asyncapi';

await asyncapi.staticSource({
  per: 'tag',
});

custom に設定すると、関数を渡して生成処理を完全にカスタマイズできます：

Example
import { asyncapi } from '@/lib/asyncapi';

await asyncapi.staticSource({
  per: 'custom',
  toPages(builder) {
    for (const [id, item] of Object.entries(builder.document.operations ?? {})) {
      const operation = builder.dereferenceShallow(item);

      builder.create({
        type: 'operation',
        schemaId: builder.id,
        item: { id, action: operation.action },
        path: `${id}.mdx`,
        info: {
          title: operation.title ?? id,
          description: operation.description,
        },
      });
    }
  },
});

tag に設定すると、タグは名前で照合されます。タグのページに説明を付けるには info.tags でタグを定義し、タイトルを指定するには x-displayName を使用します。タグのないオペレーションは unknown に分類されます。

asyncapi.yaml
info:
  tags:
    - name: lighting
      description: Operations related to streetlights.
      x-displayName: Lighting

groupBy

operation モードでは、出力ファイルをフォルダーごとにグループ化できます。

値出力
tag{tag}/{operationId}.mdx
channel{channel key}/{operationId}.mdx
none(デフォルト){operationId}.mdx
import { asyncapi } from '@/lib/asyncapi';

await asyncapi.staticSource({
  per: 'operation',
  groupBy: 'tag',
});

name

生成されるページのファイル名を制御する関数です。

import { asyncapi } from '@/lib/asyncapi';

await asyncapi.staticSource({
  name(output) {
    if (output.type === 'operation') {
      const operation = this.dereferenceShallow(this.document.operations?.[output.item.id]);
      console.log(operation);

      return `my-dir/${output.item.id}`;
    }

    return 'my-dir/filename';
  },
});

algorithm オプションを使用することもできます：

import { asyncapi } from '@/lib/asyncapi';

await asyncapi.staticSource({
  // v2(デフォルト): オペレーション ID を使用
  // v1: `{operationId}/{action}` を使用
  name: { algorithm: 'v1' },
});

meta

meta.json ファイルを自動生成します。

柔軟性を最大限に確保したい場合は、いつでも meta.json ファイルを手動で定義できます。

import { asyncapi } from '@/lib/asyncapi';

await asyncapi.staticSource({
  meta: true,
});

または、フォルダーの表示方法をカスタマイズすることもできます。

import { asyncapi } from '@/lib/asyncapi';

await asyncapi.staticSource({
  meta: {
    folderStyle: 'separator',
  },
});

MDX ファイル

ページを MDX ファイルとして書き出すには、次のようなスクリプトを作成します。

scripts/generate-docs.ts
import { generateFiles } from '@fumadocs/asyncapi';
import { asyncapi } from '@/lib/asyncapi';

void generateFiles({
  input: asyncapi,
  output: './content/docs',
  // 有効にすることをおすすめします
  // オペレーションの説明が MDX の構文を崩さないように注意してください。
  includeDescription: true,
});

スクリプトを実行してドキュメントを生成します：

bun ./scripts/generate-docs.ts

MDX コンポーネントに AsyncAPIPage コンポーネントを追加してください。生成されるファイルでは <AsyncAPIPage /> タグが使用されます。

src/routes/docs/$.tsx
import type { MDXComponents } from 'mdx/types';
import { asyncapi } from '@/lib/asyncapi';
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;
  }
}

const serverLoader = createServerFn({
  method: 'GET',
})
  .validator((slugs: string[]) => slugs)
  .handler(async ({ data: slugs }) => {
    // ...
    return {
      path: page.path,
      pageTree: await source.serializePageTree(source.getPageTree()),
      ...(await asyncapi.preloadAsyncAPIPage(page)), 
    };
  });

function Content({ path, components }: { path: string; components?: MDXComponents }) {
  // ...
  <MDX components={useMDXComponents(components)} />; 
}

function Page() {
  const { path, pageTree, preloaded } = useFumadocsLoader(Route.useLoaderData()); 

  return (
    <DocsLayout {...baseOptions()} tree={pageTree}>
      <Suspense>
        <Content
          path={path}
          components={{
            AsyncAPIPage: (props) => <AsyncAPIPage {...props} preloaded={preloaded} />,
          }}
        />
      </Suspense>
    </DocsLayout>
  );
}

loader() にプラグインを追加します。

lib/source.ts
import { asyncapi } from '@/lib/asyncapi';
import { loader } from 'fumadocs-core/source';

export const source = loader({
  // 任意: ページツリーの各ページ項目に、メッセージの方向を付加します
  plugins: [asyncapi.loaderPlugin()],
});

generateFiles() では、以下のオプションも指定できます。

index

生成されたページへのリンクカードを並べたインデックスファイルを生成します。

import { generateFiles } from '@fumadocs/asyncapi';

void generateFiles({
  index: {
    // `href` の生成に使用
    url: {
      baseUrl: '/docs',
      contentDir: './content/docs',
    },
    items: [
      {
        // 出力パス
        path: 'index.mdx',
        // 任意: 入力ファイルを限定します(サーバー側の `input` フィールドと同じ)
        only: ['streetlights.yaml'],
        // 任意: フロントマターを設定します
        description: 'All available pages',
      },
    ],
  },
});

imports

生成される MDX ファイルにカスタムのインポートを追加します。生成されるドキュメントでコンポーネントやユーティリティ、その他の依存関係を使いたい場合に便利です。

import { generateFiles } from '@fumadocs/asyncapi';

void generateFiles({
  imports: [
    {
      names: ['API_BASE_URL'],
      from: '@/constants',
    },
  ],
});

これにより、生成されるすべての MDX ファイルに次のインポートが追加されます。

import { API_BASE_URL } from '@/constants';

frontmatter

MDX ファイルのフロントマターをカスタマイズします。

デフォルトでは、次のプロパティが含まれます。

プロパティ説明
titleページのタイトル
descriptionページの説明
full常に true。Fumadocs UI 向けに追加されます
_asyncapi内部プロパティ
import { generateFiles } from '@fumadocs/asyncapi';

void generateFiles({
  frontmatter: (title, description) => ({
    myProperty: 'hello',
  }),
});

addGeneratedComment

生成されたファイルの先頭に、自動生成されたものであることを示すコメントを追加します。

import { generateFiles } from '@fumadocs/asyncapi';

void generateFiles({
  // デフォルトのコメントを追加
  addGeneratedComment: true,

  // またはカスタムコメントを指定
  addGeneratedComment: 'Custom auto-generated comment',

  // またはコメントを無効化
  addGeneratedComment: false,
});

How is this guide?

最終更新日

このページの内容

オプションpergroupBynamemetaMDX ファイルindeximportsfrontmatteraddGeneratedComment
Sponsors
General TranslationGeneral TranslationFerry HealthFerry Healthassistant-uiassistant-uiInkeepInkeep