OpenAPI

Introduction

Fumadocs provides an official OpenAPI integration to generate and document your OpenAPI schema.

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

The generate-docs script uses the OpenAPI schema to generate the documentation. You can change the OpenAPI schema by modifying the openapi.yml file in content/docs/api-reference of your project.

scripts/generate-docs.ts

import * as OpenAPI from 'fumadocs-openapi'
import { rimraf } from 'rimraf'
import { openapi } from '@/lib/openapi'

const out = './content/docs/api-reference/(generated)'

export async function generateDocs() {
  await rimraf(out, {
    filter(v) {
      return !v.endsWith('meta.json')
    },
  })

  await OpenAPI.generateFiles({
    input: openapi,
    output: out,
    per: 'operation',
    includeDescription: true,
    groupBy: 'tag',
  })
}

Only OpenAPI 3.0 and 3.1 are supported.

Generate docs with the script:

bun run build:pre

Removing the OpenAPI Integration

Follow these steps to completely remove the OpenAPI integration from your project.

Update `src/lib/source.tsx`

Comment out the OpenAPI transformer:

src/lib/source.tsx

import {
  loader,
} from 'fumadocs-core/source'
import { docs } from 'fumadocs-mdx:collections/docs'
import { openapiPlugin } from 'fumadocs-openapi/server'

export const source = loader({
  baseUrl: '/docs',
  plugins: [
    // ... other plugins
    openapiPlugin() 
  ], 
  source: docs.toFumadocsSource(),
})

Remove the OpenAPI config file

Delete the src/lib/openapi/index.ts file:

src/lib/openapi/index.ts

import {  } from 'fumadocs-openapi/server'

export const  = ({
  : ['./content/docs/api-reference/openapi.yml'],
  : '/api/proxy',
})

Delete the API reference content

Delete the API Reference folder:

rm -rf content/docs/api-reference

Remove the API Reference entry from the root meta.json:

meta.json

{
  "pages": [
    "(index)", 
    "api-reference",
    "changelog"
  ]
}

Remove the API Reference section from the homepage (src/app/(home)/page.tsx):

src/app/(home)/page.tsx

<div className="mt-8 grid grid-cols-1 gap-4 text-left md:grid-cols-2">
  <DocumentationItem
    title="Documentation"
    description="Get started with the Fumadocs framework."
    icon={{ icon: BookIcon, id: '(index)' }}
    href="/docs"
  />

  <DocumentationItem
    title="API Reference"
    description="Explore the Fumadocs API reference."
    icon={{ icon: WebhookIcon, id: 'api-reference' }}
    href="/docs/api-reference"
  />
</div>

Clean up build scripts

`scripts/generate-docs.ts`

Remove the OpenAPI generation logic:

scripts/generate-docs.ts

import * as OpenAPI from 'fumadocs-openapi'
import { rimraf } from 'rimraf'
import { openapi } from '@/lib/openapi'

export async function generateDocs() {
  await rimraf('./content/docs/api-reference/(generated)') 

  await Promise.all([ 
    OpenAPI.generateFiles({
      input: openapi,
      output: './content/docs/api-reference/(generated)',
      per: 'operation',
      includeDescription: true,
      groupBy: 'tag',
    }),
  ]) 
}

`scripts/pre-build.ts`

Remove the reference to generateDocs:

scripts/pre-build.ts

import { generateDocs } from './generate-docs.js'

async function main() {
  // comment the below to disable openapi generation /* */
  await Promise.all([generateDocs()]) 
}

Remove the API proxy

Delete the src/app/api/proxy/route.ts file.

Update global styles

Remove the OpenAPI CSS import from src/styles/globals.css:

src/styles/globals.css

@import 'tailwindcss' source(none);
@import 'fumadocs-ui/css/neutral.css';
@import 'fumadocs-ui/css/preset.css';
@import 'fumadocs-twoslash/twoslash.css';
@import 'fumadocs-openapi/css/preset.css';
@import 'tw-animate-css';

Update the docs page

Remove OpenAPI references in src/mdx-components.tsx:

src/mdx-components.tsx

import { APIPage } from '@/components/api-page'

export function getMDXComponents(components?: MDXComponents) {
  return {
    // ...
    APIPage,
    // ...
  }
}

Uninstall dependencies

Uninstall the OpenAPI dependencies:

bun remove fumadocs-openapi

After completing these steps, all OpenAPI functionality will be removed from your Fumadocs setup.