AsyncAPI

SetupCopy Anchor Link

Install the required packages.

npm i @fumadocs/asyncapi shiki

Generate StylesCopy Anchor Link

Add the following line:

@import 'tailwindcss';
@import 'fumadocs-ui/css/neutral.css';
@import 'fumadocs-ui/css/preset.css';
@import '@fumadocs/asyncapi/css/preset.css';

Configure PluginCopy Anchor Link

Create the AsyncAPI server instance & <AsyncAPIPage /> component.

import { createAsyncAPI } from '@fumadocs/asyncapi/server';

// note: this is a server-side API
export const asyncapi = createAsyncAPI({
  // the AsyncAPI schema, you can also give it an external URL.
  input: ['./asyncapi.yaml'],
});

See createAsyncAPI() & createAsyncAPIPage() for available options.

Generate PagesCopy Anchor Link

Integrate into Loader API to generate pages, without generating real files.

import { loader } from 'fumadocs-core/source';
import { defineDocs } from 'fumadocs-mdx/macro';
import { asyncapi } from '@/lib/asyncapi'; 

const docs = defineDocs({
  dir: 'content/docs',
});

export const source = loader(
  {
    docs: docs.toFumadocsSource(),
    asyncapi: await asyncapi.staticSource({
      baseDir: 'asyncapi',
    }),
  },
  {
    baseUrl: '/docs',
    // optional: adds the direction of messages to each page item in page tree
    plugins: [asyncapi.loaderPlugin()],
  },
);

It generates a page per operation by default, see Generating Pages to customize them.

It will change the type of your pages, make sure to update all references to your source.

For example, where you return text for 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')}`;
    }

    // your original flow below...
  },
});

And update your page renderer:

import { AsyncAPIPage } from '@/components/api-page'; 

export default async function Page(props: PageProps<'/docs/[[...slug]]'>) {
  const params = await props.params;
  const page = source.getPage(params.slug);
  if (!page) notFound();

  if (page.type === 'asyncapi') {
    return (
      <DocsPage full>
        <DocsTitle>{page.data.title}</DocsTitle>
        <DocsBody>
          <AsyncAPIPage {...page.data.getAsyncAPIPageProps()} />
        </DocsBody>
      </DocsPage>
    );
  }

  // ...
}

npm run types:check

To write MDX files into your content directory instead, see MDX Files.

FeaturesCopy Anchor Link

The official AsyncAPI integration supports AsyncAPI 3:

• The direction of messages for readers, the server and channel address of operations
• Messages with their payload and header schemas, including Avro, Protobuf and RAML schemas
• Message examples, from the document or generated from schemas
• Request and reply, correlation IDs
• Security schemes, including OAuth 2.0 flows and SASL mechanisms
• Protocol details from bindings, for the selected server
• A playground for WebSocket, Server-Sent Events and custom transports, with text and binary messages
• Code samples in JavaScript and Python, for WebSocket, MQTT, Kafka, AMQP and NATS
• TypeScript definitions of payloads and headers
• Markdown of pages for LLMs
• Traits

AsyncAPI 2 documents can be converted with npx @asyncapi/cli convert.

DemoCopy Anchor Link

See the AsyncAPI example.