OpenAPI Generator

Usage

Install the required packages.

npm install fumadocs-openapi

Generate Styles

The interactive UI of OpenAPI integration is styled with Tailwind CSS, it doesn't include a pre-built stylesheet by default. You must use it in conjunction with the official Tailwind CSS plugin.

Add the package to content under your Tailwind CSS configuration.

tailwind.config.js

import { createPreset } from 'fumadocs-ui/tailwind-plugin';
 
/** @type {import('tailwindcss').Config} */
export default {
  content: [
    './node_modules/fumadocs-ui/dist/**/*.js',
    './node_modules/fumadocs-openapi/dist/**/*.js',
  ],
  presets: [createPreset()],
};

Generate Files

Create a script:

scripts/generate-docs.mjs

import { generateFiles } from 'fumadocs-openapi';
 
void generateFiles({
  input: ['./petstore.yaml'], // the OpenAPI schemas
  output: './content/docs',
});

Only OpenAPI 3.0 is supported.

It doesn't allow JSON schema specific keywords like const, as they are unsupported

Generate docs with the script:

node ./scripts/generate-docs.mjs

Fumadocs OpenAPI generates MDX content directly, you can use a formatter (e.g. Prettier) to format the output files.

Generate Page Tree

You can add the attachFile to decorate the page tree with Source API.

It adds a badge to each page item.

source.ts

import { createMDXSource, defaultSchemas } from 'fumadocs-mdx';
import { z } from 'zod';
import { loader } from 'fumadocs-core/source';
import { attachFile } from 'fumadocs-openapi/source';
 
const frontmatter = defaultSchemas.frontmatter.extend({
  method: z.string().optional(),
});
 
export const utils = loader({
  source: createMDXSource(map, {
    schema: {
      frontmatter,
    },
  }),
  pageTree: {
    attachFile,
  },
  // other props
});

Features

The official OpenAPI integration supports:

Basic API endpoint information
Interactive API playground
Example code to send request (in different programming languages)
Response samples and TypeScript definitions
Request parameters and body generated from schemas

Demo

View demo.

Options

You can also pass options to the generateFiles function.

Input

An array of input files (path), wildcard allowed.

Output

Path to the output directory.

Per

Customise how the page is generated, default to file.

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 Folder

In operation mode, you can group operations with folders.

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

Name

A function that controls the output path of files.

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

Imports

The imports on the top of MDX files. When not specified, it imports the required components from the package itself.

import { generateFiles } from 'fumadocs-openapi';
 
void generateFiles({
  input: ['./petstore.yaml'],
  output: './content/docs',
  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',
  }),
});

Generate Code Samples

Generate custom code samples for each API endpoint.

import { generateFiles } from 'fumadocs-openapi';
 
void generateFiles({
  input: ['./petstore.yaml'],
  output: './content/docs',
  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 how components are generated.

import { generateFiles, createElement } from 'fumadocs-openapi';
 
void generateFiles({
  input: ['./petstore.yaml'],
  output: './content/docs',
  renderer: {
    Root(props, child) {
      return createElement(
        'Root',
        props,
        '<div className="bg-fd-secondary p-4 rounded-lg">Demo Only</div>',
        ...child,
      );
    },
  },
});

OpenAPI Generator

On this page