OpenAPI

Manual Setup

Install the required packages.

npm install fumadocs-openapi shiki

Generate Styles

The interactive UI of OpenAPI integration is styled with Tailwind CSS, it doesn't include a pre-built stylesheet. You must use it with Tailwind CSS configured.

Add the package to @source in your Tailwind CSS configuration.

Tailwind CSS

@import 'tailwindcss';
@import 'fumadocs-ui/css/neutral.css';
@import 'fumadocs-ui/css/preset.css';
 
@source '../node_modules/fumadocs-ui/dist/**/*.js';
@source '../node_modules/fumadocs-openapi/dist/**/*.js';

Configure Pages

Create an OpenAPI instance on the server. Fumadocs OpenAPI renders the pages on server-side.

lib/source.ts

import { createOpenAPI, attachFile } from 'fumadocs-openapi/server';
import { loader } from 'fumadocs-core/source';
 
export const source = loader({
  pageTree: {
    // adds a badge to each page item in page tree
    attachFile,
  },
  // other props
});
 
export const openapi = createOpenAPI({
  // options
});

Add APIPage to your MDX Components, so that you can use it in MDX files.

mdx-components.tsx

import defaultComponents from 'fumadocs-ui/mdx';
import { APIPage } from 'fumadocs-openapi/ui';
import { openapi } from '@/lib/source';
import type { MDXComponents } from 'mdx/types';
 
export function getMDXComponents(components?: MDXComponents): MDXComponents {
  return {
    ...defaultComponents,
    APIPage: (props) => <APIPage {...openapi.getAPIPageProps(props)} />,
    ...components,
  };
}

It is a React Server Component.

Generate Files

You can generate MDX files directly from your OpenAPI schema.

Create a script:

scripts/generate-docs.mjs

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

Only OpenAPI 3.0 and 3.1 are supported.

Generate docs with the script:

node ./scripts/generate-docs.mjs

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.