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

Installing the types packages is highly recommended for advanced customisations:

npm install openapi-types json-schema-typed -D

It gives you a higher level of type-safety.

Generate Code Samples

Generate custom code samples for each API endpoint.

import { openapi } from '@/lib/openapi';
import { createAPIPage } from 'fumadocs-openapi/ui';

export const APIPage = createAPIPage(openapi, {
  generateCodeSamples(endpoint) {
    return [
      {
        id: 'js',
        lang: 'js',
        label: 'JavaScript SDK',
        source: "console.log('hello')",
      },
      // or to disable the default code samples
      // set `source: false`
      {
        id: 'curl',
        lang: 'bash',
        source: false,
      },
    ];
  },
});

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

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.

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

export const mediaAdapters: Record<string, MediaAdapter> = {
  // example: custom `application/json
  'application/json': {
    encode(data) {
      return JSON.stringify(data.body);
    },
    // returns code that inits a `body` variable, used for request body
    generateExample(data, ctx) {
      if (ctx.lang === 'js') {
        return `const body = "hello world"`;
      }

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

      if (ctx.lang === 'go' && 'addImport' in ctx) {
        ctx.addImport('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/media-adapters';
import client from './api-page.client';

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