Fumadocs

generateFiles()

Generate pages from AsyncAPI schema.

The generateFiles() function generates MDX files for API documentation.

Note that the page content is still rendered by the <AsyncAPIPage /> component, the docs generator only arranges the operations to render for each page.

Usage

It takes an AsyncAPI instance.

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

void generateFiles({
  input: asyncapi,
  // The output directory.
  output: '/content/docs',
});

per

Customize the content of pages, default to operation.

Operation refers to an AsyncAPI operation with a specific action like receiveLightMeasurement:receive.

modecontentfile path
tagoperations with same tag{tag_name}.mdx
fileoperations in same schema file{file_name}.mdx
operationeach operation{operationId}.mdx
customsee belowN/A
import { generateFiles } from '@fumadocs/asyncapi';

void generateFiles({
  per: 'tag',
});

When set to custom, you can pass a function to fully customize the generation process:

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

void generateFiles({
  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,
        },
      });
    }
  },
});

When set to tag, tags are matched by name. Define them in info.tags to give their pages a description, and x-displayName to control the title. Operations without tags are under unknown.

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

groupBy

In operation mode, you can group output files with folders.

valueoutput
tag{tag}/{operationId}.mdx
channel{channel key}/{operationId}.mdx
none (default){operationId}.mdx
import { generateFiles } from '@fumadocs/asyncapi';

void generateFiles({
  per: 'operation',
  groupBy: 'tag',
});

index

Generate index files with cards linking to generated pages.

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

void generateFiles({
  index: {
    // for generating `href`
    url: {
      baseUrl: '/docs',
      contentDir: './content/docs',
    },
    items: [
      {
        // output path
        path: 'index.mdx',
        // optional: restrict the input files (identical to the `input` field in server)
        only: ['streetlights.yaml'],
        // optional: set frontmatter
        description: 'All available pages',
      },
    ],
  },
});

meta

Generate meta.json files automatically.

You can always define the meta.json files manually for maximal flexibility.

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

void generateFiles({
  meta: true,

  // or customize how folders are represented:
  meta: {
    folderStyle: 'separator',
  },
});

imports

Add custom imports to generated MDX files. This is useful for including components, utilities, or other dependencies in your generated documentation.

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

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

This will add the following imports to all generated MDX files:

import { API_BASE_URL } from '@/constants';

name

A function that controls the output file name of MDX pages.

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

void generateFiles({
  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';
  },
});

You can also use the algorithm option:

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

void generateFiles({
  // v2 (default): use operation id
  // v1: use `{operationId}/{action}`
  name: { algorithm: 'v1' },
});

frontmatter

Customize the frontmatter of MDX files.

By default, it includes:

propertydescription
titlePage title
descriptionPage description
fullAlways true, added for Fumadocs UI
_asyncapiInternal Properties
import { generateFiles } from '@fumadocs/asyncapi';

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

addGeneratedComment

Add a comment to the top of generated files indicating they are auto-generated.

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

void generateFiles({
  // Add default comment
  addGeneratedComment: true,

  // Or provide a custom comment
  addGeneratedComment: 'Custom auto-generated comment',

  // Or disable comments
  addGeneratedComment: false,
});

How is this guide?

Last updated on

On this page

UsagepergroupByindexmetaimportsnamefrontmatteraddGeneratedComment
Sponsors
General TranslationGeneral TranslationFerry HealthFerry Healthassistant-uiassistant-uiInkeepInkeep