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

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,
});

bun ./scripts/generate-docs.ts

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} />
        ),
      })}
    />
  );
}

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.