createOpenAPIPage()

Overview

Fumadocs OpenAPI uses a <OpenAPIPage /> component to render page contents, it should be a client component.

components/api-page.tsx

'use client';
import { createOpenAPIPage } from 'fumadocs-openapi/ui';

export const OpenAPIPage = createOpenAPIPage({
  // config
});

Generate Code Usages

Generate code usage examples for each API endpoint.

components/api-page.tsx

'use client';
import {  } from 'fumadocs-openapi/ui';
import {
  ,
  type ,
} from 'fumadocs-openapi/requests/generators';
import {  } from 'fumadocs-openapi/requests/generators/all';

const  = ();

// include defaults
();

// add custom generators
.('custom-id', {
  : 'My Example',
  : 'js',
  (, {  }) {
    // request data
    .();

    return 'const response = "hello world";';
  },
});

export const  = ({
  ,
});

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 });

Internationalization

Assuming you have configured Internationalization at UI level:

layout.shared.tsx

import { defineI18n } from 'fumadocs-core/i18n';
import { uiTranslations } from 'fumadocs-ui/i18n';
import { openapiTranslations } from 'fumadocs-openapi/i18n';

const i18n = defineI18n({
  languages: ['en', 'cn'],
  defaultLanguage: 'en',
});

export const translations = i18n
  .translations()
  .extend(uiTranslations())
  .extend(openapiTranslations())
  .add({
    cn: {
      displayName: 'Chinese',
      'Body(playground)': '請求正文',
    },
  });

See Translations for more details.

Media Adapters

You can create a media adapter to support other media types in API pages, a media adapter implements:

Converting value into fetch() body compatible with corresponding media type.
Generate code example based on different programming language/tool.

components/api-page.tsx

'use client';
import {  } from 'fumadocs-openapi/ui';
import type { MediaAdapter } from 'fumadocs-openapi';

const : <string, MediaAdapter> = {
  // example: custom `application/json
  'application/json': {
    () {
      return .(.);
    },
    // returns code that inits a `body` variable, used for request body
    (, ) {
      if (. === 'js') {
        return `const body = "hello world"`;
      }

      if (. === 'python') {
        return `body = "hello world"`;
      }

      if (. === 'go' && 'addImport' in ) {
        .('strings');

        return `body := strings.NewReader("hello world")`;
      }
    },
  },
};

export const  = ({
  ,
});

Customise UI

For customisations beyond the available options, you can install the UI into your codebase with Fumadocs CLI.

Full UI

The entire UI of API pages, built on the headless layer.

npx @fumadocs/cli add fumadocs/openapi/page

It installs <OpenAPIPage /> itself, your components/api-page.tsx is no longer needed.

mdx-components.tsx

import { OpenAPIPage } from '@/components/api-page';
import { OpenAPIPage } from '@/components/openapi/page';

API Playground

npx @fumadocs/cli add fumadocs/openapi/playground

components/api-page.tsx

'use client';
import { createOpenAPIPage } from 'fumadocs-openapi/ui';
import PlaygroundClient from '@/components/openapi/playground';

export const OpenAPIPage = createOpenAPIPage({
  playground: {
    render: ({ path, method, operation, pathItem }) => (
      <PlaygroundClient
        route={path}
        method={method}
        operation={operation}
        pathItem={pathItem}
        writeOnly
        readOnly={false}
      />
    ),
  },
});

Operation

The UI of operations and webhooks.

npx @fumadocs/cli add fumadocs/openapi/operation

components/api-page.tsx

'use client';
import { createOpenAPIPage } from 'fumadocs-openapi/ui';
import { Operation } from '@/components/openapi/operation';

export const OpenAPIPage = createOpenAPIPage({
  components: {
    Operation,
  },
});

Schema UI

The UI for rendering JSON schemas.

npx @fumadocs/cli add fumadocs/api-docs/schema

components/api-page.tsx

'use client';
import { createOpenAPIPage } from 'fumadocs-openapi/ui';
import { Schema } from '@/components/api/schema';

export const OpenAPIPage = createOpenAPIPage({
  components: {
    SchemaUI: Schema,
  },
});

createOpenAPIPage()

On this page