---
title: Configurations
description: Customise Fumadocs OpenAPI
---

## File Generator

Pass options to the `generateFiles` function.

### Input

An array of input files.
Allowed:

- File Paths
- External URLs
- Wildcard

```ts
import { generateFiles } from 'fumadocs-openapi';

void generateFiles({
  input: ['./unkey.json'],
});
```

On Next.js server, the schema is dynamically fetched when the `APIPage` component renders.

<Callout type='warn' title='For Vercel'>

    If the schema is passed as a file path, ensure the page **will not** be re-rendered after build.

</Callout>

### Output

Path to the output directory.

```ts
import { generateFiles } from 'fumadocs-openapi';

void generateFiles({
  output: '/content/docs',
});
```

### Per

Customise how the page is generated, default to `operation`.

| mode      | Generate a page for                 |
| --------- | ----------------------------------- |
| tag       | each tag                            |
| file      | each schema                         |
| operation | each operation (method of endpoint) |

```ts
import { generateFiles } from 'fumadocs-openapi';

void generateFiles({
  per: 'tag',
});
```

### Group By

In `operation` mode, you can group output files with folders.

| Group by | Description                                                  |
| -------- | ------------------------------------------------------------ |
| tag      | `{tag}/{page}.mdx` (Each operation can only contain `1` tag) |
| route    | `{api-endpoint}/{page}.mdx`                                  |
| none     | `{page}.mdx` (default)                                       |

```ts
import { generateFiles } from 'fumadocs-openapi';

void generateFiles({
  per: 'operation',
  groupBy: 'tag',
});
```

### Name

A function that controls the output path of files.

```ts
import { generateFiles } from 'fumadocs-openapi';

void generateFiles({
  name: (type, file) => {
    return; // filename
  },
});
```

### Imports

Add additional imports on the top of MDX files.

```ts
import { generateFiles } from 'fumadocs-openapi';

void generateFiles({
  imports: [
    {
      names: ['Component1', 'Component2'],
      from: '@/components/ui/api',
    },
  ],
});
```

### Frontmatter

Customise the frontmatter of MDX files.

By default, it includes:

| property      | description                                      |
| ------------- | ------------------------------------------------ |
| `title`       | Page title                                       |
| `description` | Page description                                 |
| `full`        | Always true, added for Fumadocs UI               |
| `method`      | Available method of operation (`operation` mode) |
| `route`       | Route of operation (`operation` mode)            |

```ts
import { generateFiles } from 'fumadocs-openapi';

void generateFiles({
  input: ['./petstore.yaml'],
  output: './content/docs',
  frontmatter: (title, description) => ({
    myProperty: 'hello',
  }),
});
```

### Tag Display Name

Adding `x-displayName` to OpenAPI Schema can control the display name of your tags.

```yaml title="openapi.yaml"
tags:
  - name: test
    description: this is a tag.
    x-displayName: My Test Name
```

## OpenAPI Server

The server to render pages.

### Generate Code Samples

Generate custom code samples for each API endpoint.

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

export const openapi = createOpenAPI({
  generateCodeSamples(endpoint) {
    return [
      {
        lang: 'js',
        label: 'JavaScript SDK',
        source: "console.log('hello')",
      },
    ];
  },
});
```

In addition, you can also specify code samples via OpenAPI schema.

```yaml
paths:
  /plants:
    get:
      x-codeSamples:
        - lang: js
          label: JavaScript SDK
          source: |
            const planter = require('planter');
            planter.list({ unwatered: true });
```

### Renderer

Customise components in the page.

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

export const openapi = createOpenAPI({
  renderer: {
    Root(props) {
      // your own (server) component
    },
  },
});
```

## Advanced

### Using API Page

> This is not a public API, use it carefully.

To use the `APIPage` component in your MDX files:

```mdx
---
title: Delete Api
full: true
---

<APIPage
  document="./unkey.json"
  operations={[{ path: '/v1/apis.deleteApi', method: 'post' }]}
  hasHead={false}
/>
```

| Prop         | Description                               |
| ------------ | ----------------------------------------- |
| `document`   | OpenAPI Schema                            |
| `operations` | Operations (API endpoints) to be rendered |
| `hasHead`    | Enable to render the heading of operation |
