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.

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	description
tag	Generate a page for each tag
file	Generate a page for each schema

Name

A function that controls the output path of files.

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

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 a full: true property for Fumadocs UI.

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-secondary p-4 rounded-lg">Demo Only</div>',
        ...child,
      );
    },
  },
});

OpenAPI Generator

On this page