Configurations

File Generator

Pass options to the generateFiles function.

Input

OpenAPI Server object.
anything supported by input.

import { generateFiles } from 'fumadocs-openapi';

void generateFiles({
  input: ['./unkey.json'],
});

Output

The output directory.

import { generateFiles } from 'fumadocs-openapi';

void generateFiles({
  output: '/content/docs',
});

Per

Customise how the page is generated, default to operation.

Operation refers to an API endpoint with specific method like /api/weather:GET.

mode		output
tag	operations with same tag	`{tag_name}.mdx`
file	operations in schema schema	`{file_name}.mdx`
operation	each operation	`{operationId ?? endpoint_path}.mdx`)

import { generateFiles } from 'fumadocs-openapi';

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

Group By

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

value	output
tag	`{tag}/{operationId ?? endpoint_path}.mdx`
route	`{endpoint_path}/{method}.mdx` (ignores `name` option)
none	`{operationId ?? endpoint_path}.mdx` (default)

import { generateFiles } from 'fumadocs-openapi';

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

Index

Generate index files with cards linking to generated pages.

import { generateFiles } from 'fumadocs-openapi';

void generateFiles({
  input: ['./petstore.yaml', './museum.yaml'],
  output: './content/docs',

  index: {
    // for generating `href`
    url: {
      baseUrl: '/docs',
      contentDir: './content/docs',
    },
    items: [
      {
        path: 'index.mdx',
        // optional: restrict the input files
        only: ['petstore.yaml'],
        // optional: set frontmatter
        description: 'All available pages',
      },
    ],
  },
});

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-openapi';

void generateFiles({
  input: ['./petstore.yaml'],
  output: './content/docs',
  imports: [
    {
      names: ['CustomComponent', 'AnotherComponent'],
      from: '@/components/custom',
    },
    {
      names: ['utils'],
      from: '@/lib/utils',
    },
    {
      names: ['API_BASE_URL'],
      from: '@/constants',
    },
  ],
});

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

import { CustomComponent, AnotherComponent } from '@/components/custom';
import { utils } from '@/lib/utils';
import { API_BASE_URL } from '@/constants';

The imports configuration is especially important for Cards generation in index files, where you need to import source and getPageTreePeers for the navigation functionality to work.

Name

A function that controls the output path of MDX pages.

import { generateFiles } from 'fumadocs-openapi';

void generateFiles({
  name: (output, document) => {
    if (output.type === 'operation') {
      const operation = document.paths![output.item.path]![output.item.method]!;
      // operation object
      console.log(operation);

      return 'my-dir/filename';
    }

    const hook = document.webhooks![output.item.name][output.item.method]!;
    // webhook object
    console.log(hook);
    return 'my-dir/filename';
  },
});

Frontmatter

Customise the frontmatter of MDX files.

By default, it includes:

property	description
`title`	Page title
`description`	Page description
`full`	Always true, added for Fumadocs UI
`method`	Available method of operation (`operation` mode)
`route`	Route of operation (`operation` mode)

import { generateFiles } from 'fumadocs-openapi';

void generateFiles({
  input: ['./petstore.yaml'],
  output: './content/docs',
  frontmatter: (title, description) => ({
    myProperty: 'hello',
  }),
});

Add Generated Comment

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

import { generateFiles } from 'fumadocs-openapi';

void generateFiles({
  input: ['./petstore.yaml'],
  output: './content/docs',
  // Add default comment
  addGeneratedComment: true,

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

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

Tag Display Name

Adding x-displayName to OpenAPI Schema can control the display name of your tags.

openapi.yaml

tags:
  - name: test
    description: this is a tag.
    x-displayName: My Test Name

OpenAPI Server

The server to render pages.

Input

File Paths
External URLs
A function (see below)

import { createOpenAPI } from 'fumadocs-openapi/server';

export const openapi = createOpenAPI({
  input: ['./unkey.json'],
});

Generate Code Samples

Generate custom code samples for each API endpoint. Make sure to install the types package to give you type-safety when customising it:

npm install openapi-types -D

import { createOpenAPI } from 'fumadocs-openapi/server';

export const openapi = createOpenAPI({
  generateCodeSamples(endpoint) {
    return [
      {
        lang: 'js',
        label: 'JavaScript SDK',
        source: "console.log('hello')",
      },
    ];
  },
});

In addition, you can also specify code samples via OpenAPI schema.

paths:
  /plants:
    get:
      x-codeSamples:
        - lang: js
          label: JavaScript SDK
          source: |
            const planter = require('planter');
            planter.list({ unwatered: true });

Disable Code Sample

You can disable the code sample for a specific language, for example, to disable cURL:

import { createOpenAPI } from 'fumadocs-openapi/server';

export const openapi = createOpenAPI({
  generateCodeSamples(endpoint) {
    return [
      {
        lang: 'curl',
        label: 'cURL',
        source: false,
      },
    ];
  },
});

Renderer

Customise components in the page.

import { createOpenAPI } from 'fumadocs-openapi/server';

export const openapi = createOpenAPI({
  renderer: {
    Root(props) {
      // your own (server) component
    },
  },
});

On this page