OpenAPI

Setup

openapiPlugin() renders OpenAPI pages with the interactive playground.

npm i fumadocs-openapi shiki

Add its styles:

src/styles/global.css

@import 'tailwindcss';
@import 'fumadocs-ui/css/neutral.css';
@import 'fumadocs-ui/css/preset.css';
@import 'fumadocs-openapi/css/preset.css';

Create the OpenAPI server from your schema:

src/lib/openapi.ts

import { createOpenAPI } from 'fumadocs-openapi/server';

export const openapi = createOpenAPI({
  input: ['./openapi.yaml'],
});

Add its pages to your source:

src/lib/source.ts

import { getCollection } from 'astro:content';
import { loader } from 'fumadocs-core/source';
import { toFumadocsSource } from '@fumadocs/astro/source';
import { openapi } from './openapi'; 

export const source = loader({
  source: {
    docs: toFumadocsSource(await getCollection('docs'), await getCollection('meta')),
    api: await openapi.staticSource({ baseDir: 'api' }), 
  },
  baseUrl: '/docs',
  // adds a badge to each page in the sidebar
  plugins: [openapi.loaderPlugin()],
});

It generates a page per operation under /docs/api, see Generating Pages to customize them. Generated MDX files are not supported, use staticSource() above.

Render them with the plugin:

src/fumadocs.config.ts

import { defineConfig } from '@fumadocs/astro/config';
import { openapiPlugin } from '@fumadocs/astro/plugins/openapi'; 
import { source } from './lib/source';
import { openapi } from './lib/openapi'; 

export default defineConfig({
  source,
  plugins: [openapiPlugin({ server: openapi })], 
});

The plugin follows your server: it serves the documents left out by includeDocument: false, and the proxy at proxyUrl when it is a pathname (requires an Astro adapter). See OpenAPI server options.

Pass proxy options with createProxy, or false when the proxy is served elsewhere:

src/fumadocs.config.ts

openapiPlugin({
  server: openapi,
  createProxy: { allowedOrigins: ['https://api.example.com'] }, 
});

To customize the pages, create <OpenAPIPage /> with createOpenAPIPage() and add it to your MDX components, loaded lazily (see Lazy Components).

SetupCopy Anchor Link

On this page

Setup