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 and the <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() and createAsyncAPIPage() for their options.

Generate PagesCopy Anchor Link

Pass staticSource() to your loader(). It generates pages without writing files.

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',
    // optional: adds the direction of messages to each page item in page tree
    plugins: [asyncapi.loaderPlugin()],
  },
);

staticSource() generates a page per operation by default. See Generating Pages to customize them.

Pages of source now have two types, docs and asyncapi. Update every place that uses source, like where you return text for LLMs:

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

Render AsyncAPI pages in an island of their own, which wraps <AsyncAPIPage /> with the docs layout:

---
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

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.