Configurations

File Generator

Pass options to the generateFiles function.

Input

An array of input files. Allowed:

File Paths
External URLs
Wildcard

import { generateFiles } from 'fumadocs-openapi';
 
void generateFiles({
  input: ['./unkey.json'],
});

On Next.js server, the schema is dynamically fetched when the APIPage component renders.

For Vercel

If the schema is passed as a file path, ensure the page will not be re-rendered after build.

Output

Path to the output directory.

import { generateFiles } from 'fumadocs-openapi';
 
void generateFiles({
  output: '/content/docs',
});

Per

Customise how the page is generated, default to operation.

mode	Generate a page for
tag	each tag
file	each schema
operation	each operation (method of endpoint)

import { generateFiles } from 'fumadocs-openapi';
 
void generateFiles({
  per: 'tag',
});

Group By

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

Group by	Description
tag	`{tag}/{page}.mdx` (Each operation can only contain `1` tag)
route	`{api-endpoint}/{page}.mdx`
none	`{page}.mdx` (default)

import { generateFiles } from 'fumadocs-openapi';
 
void generateFiles({
  per: 'operation',
  groupBy: 'tag',
});

Name

A function that controls the output path of files.

import { generateFiles } from 'fumadocs-openapi';
 
void generateFiles({
  name: (type, file) => {
    return; // filename
  },
});

Imports

Add additional imports on the top of MDX files.

import { generateFiles } from 'fumadocs-openapi';
 
void generateFiles({
  imports: [
    {
      names: ['Component1', 'Component2'],
      from: '@/components/ui/api',
    },
  ],
});

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

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.

Generate Code Samples

Generate custom code samples for each API endpoint.

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

Renderer

Customise components in the page.

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

Advanced

Using API Page

This is not a public API, use it carefully.

To use the APIPage component in your MDX files:

---
title: Delete Api
full: true
---
 
<APIPage
  document="./unkey.json"
  operations={[{ path: '/v1/apis.deleteApi', method: 'post' }]}
  hasHead={false}
/>

Prop	Description
`document`	OpenAPI Schema
`operations`	Operations (API endpoints) to be rendered
`hasHead`	Enable to render the heading of operation

On this page