Overview
Introduction
API documentation allows you to automatically generate interactive reference pages for your API specifications directly inside your documentation site. By supplying your specification documents, the software builds structured pages complete with operation details, code examples, schemas, and testing tools so readers can easily understand and interact with your APIs.
Note
Supported API specification formats include OpenAPI and AsyncAPI.
Generating Reference Pages
Setting Up the Server
You can set up your server to load specification documents and turn them into navigable documentation pages automatically.
Initialize an API server instance for your chosen specification type and point it to your input documents. You can provide an array of file paths or URLs, or supply a custom record of documents.
import { createOpenAPI } from 'fumadocs-openapi/server';
export const openapi = createOpenAPI({
input: ['./spec.json'],
});Tip
Supported providers / spec configurations: input, disableCache, proxyUrl.
Building Virtual Files
Generate virtual source pages from your loaded schemas using either static or dynamic loading options.
export const source = openapi.staticSource({
baseDir: 'api',
meta: true,
});Key Concepts
- OpenAPI: A specification format for describing RESTful HTTP APIs, including endpoints, methods, parameters, and responses.
- AsyncAPI: A specification format for describing event-driven architectures, messaging protocols, and asynchronous operations.
- Virtual Files: Automatically generated documentation pages created from your raw specification files without needing to write individual Markdown files manually.
- Playground: An interactive tool embedded in documentation pages that lets users test API requests or operations live.
Configuration Options
When setting up your automatic page generation, you can configure how files and folders are structured.
| Option | Type | Description |
|---|---|---|
per | string | Determines how pages are split (operation, tag, file, or custom). |
groupBy | string / function | Groups operations into folders by tag, route, or none. |
baseDir | string | The base directory path for generated virtual files. |
meta | boolean / object | Generates meta.json files automatically with folder styling options. |
Warning
When setting groupBy to tag, make sure that a tags property is defined for every operation in your schema to avoid fallback warnings.
Customizing User Interfaces
User Interface Settings
You can customize how the API reference pages appear and behave by passing options into your page components.
- Code Usages: Generate example code snippets in multiple programming languages for every endpoint.
- TypeScript Definitions: Automatically generate TypeScript types from JSON schemas for requests and responses.
- Playground Integration: Enable interactive request testing using built-in tools or external clients like Scalar.
import { createOpenAPIPage } from 'fumadocs-openapi/ui';
export const OpenAPIPage = createOpenAPIPage({
showResponseSchema: true,
});Tip
To use Scalar as your API testing client, wrap your options with the Scalar provider helper (withScalar).