<APIPage />

Overview

Fumadocs OpenAPI uses a <APIPage /> component to render page contents.

When customising it, the options are split into server/client configs.

import { openapi } from '@/lib/openapi';
import { createAPIPage } from 'fumadocs-openapi/ui';
import client from './api-page.client';

export const APIPage = createAPIPage(openapi, {
  client,
  // server config
});

Generate Code Usages

Generate code usage examples for each API endpoint.

lib/openapi/code-usage.ts

import {
  ,
  type CodeUsageGenerator,
} from 'fumadocs-openapi/requests/generators';
import {  } from 'fumadocs-openapi/requests/generators/all';

export const  = ();

// include defaults
();

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

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

Pass the registry to both client & server configs:

import { openapi } from '@/lib/openapi';
import { createAPIPage } from 'fumadocs-openapi/ui';
import { codeUsages } from '@/lib/openapi/code-usage';
import client from './api-page.client';

export const APIPage = createAPIPage(openapi, {
  client,
  codeUsages,
});

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 { defineI18nUI } from 'fumadocs-ui/i18n';
import { defineI18nOpenAPI } from 'fumadocs-openapi/i18n';

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

export let i18nUI = defineI18nUI(i18n, {
  cn: { displayName: 'Chinese' },
});

i18nUI = defineI18nOpenAPI(i18nUI, {
  cn: {
    titleRequestBody: '請求正文',
  },
});

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.

Put your media adapters in a separate file.

lib/openapi/media.ts

import type { MediaAdapter } from 'fumadocs-openapi';

export 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")`;
      }
    },
  },
};

Pass the adapter to both client & server configs.

import { openapi } from '@/lib/openapi';
import { createAPIPage } from 'fumadocs-openapi/ui';
import { mediaAdapters } from '@/lib/openapi/media';
import client from './api-page.client';

export const APIPage = createAPIPage(openapi, {
  client,
  mediaAdapters,
});

Overview

Generate Code Usages

Internationalization

Media Adapters

On this page