AsyncAPI

Setup

Install the required packages.

npm i @fumadocs/asyncapi shiki

Generate Styles

Add the following line:

Tailwind CSS

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

Configure Plugin

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 Pages

You can generate MDX files directly from your AsyncAPI schema.

Create a script:

scripts/generate-docs.ts

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

void generateFiles({
  input: asyncapi,
  output: './content/docs',
  // we recommend to enable it
  // make sure your operation description doesn't break MDX syntax.
  includeDescription: true,
});

Generate docs with the script:

bun ./scripts/generate-docs.ts

Add the AsyncAPIPage component to your MDX components. Generated files use the <APIPage /> tag.

app/docs/[[...slug]]/page.tsx

import { source } from '@/lib/source';
import { asyncapi } from '@/lib/asyncapi';
import { AsyncAPIPage } from '@/components/api-page';
import { getMDXComponents } from '@/components/mdx';

// e.g. in your page renderer
export default function Page({ slug }) {
  const page = source.getPage(slug);
  const MdxContent = page.data.body;

  return (
    <MdxContent
      components={getMDXComponents({
        // add the MDX component
        AsyncAPIPage: async (props) => (
          <AsyncAPIPage {...await asyncapi.preloadAsyncAPIPage(page)} {...props} />
        ),
      })}
    />
  );
}

Features

The official AsyncAPI integration supports:

Basic operation information (send/receive)
Channel, message, and reply documentation
Message payload & header schemas
Security schemes
Message examples (from schema examples or generated samples)
Bindings and traits

Demo

See the AsyncAPI example.