OpenAPI

Build API documentations with Fumapress.

Installation

npm i fumadocs-openapi shiki

Import the CSS preset in src/app.css:

src/app.css

@import "tailwindcss";
@import "fumadocs-ui/css/neutral.css";
@import "fumadocs-ui/css/preset.css";
@import "fumapress/css/preset.css";
@import "fumadocs-openapi/css/preset.css";

Configure the plugin:

press.config.tsx

import { defineConfig } from "fumapress";
import { defineDocs } from "fumadocs-mdx/macro";
import path from "node:path";
import { createOpenAPI } from "fumadocs-openapi/server";
import { openapiPlugin } from "fumapress/plugins/openapi";

const docs = defineDocs({
  dir: "content/docs",
  docs: { async: true },
});

const openapi = createOpenAPI({
  // path or URL to your OpenAPI spec
  input: [path.resolve("./openapi.json")],
});

export default defineConfig({
  content: {
    docs: docs.toFumadocsSource(),
    openapi: await openapi.staticSource(),
  },
})
  // fumapress plugin
  .plugins(openapiPlugin({ server: openapi }));

Update the path/URL to your OpenAPI spec (e.g. ./openapi.json), the API pages will be automatically generated based on your spec.

Options

You can see Fumadocs OpenAPI for details of advanced options.

`openapi.staticSource()`

It support a subset of options from generateFiles().

How to customize its output file structure?

It accepts a baseDir option. For example, the following will generate all API pages under the (openapi) folder:

press.config.tsx

import { defineConfig } from "fumapress";
import { defineDocs } from "fumadocs-mdx/macro";

const docs = defineDocs({
  dir: "content/docs",
  docs: { async: true },
});

export default defineConfig({
  content: {
    docs: docs.toFumadocsSource(),
    openapi: await openapi.staticSource({
      baseDir: "(openapi)",
    }),
  },
});

Client UI

Create the renderer for API pages explicitly:

src/components/openapi.tsx

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

export const OpenAPIPage = createOpenAPIPage();

And import it from the OpenAPI plugin:

press.config.tsx

import { OpenAPIPage } from "./src/components/openapi";

export default defineConfig({
  // ...
}).plugins(
  openapiPlugin({
    server: openapi,
    ClientAPIPage: OpenAPIPage,
  }),
);

Proxy Server

To create the Proxy Server, define proxyUrl in createOpenAPI() and pass allowedOrigins to the plugin:

press.config.tsx

import { defineConfig } from "fumapress";
import { createOpenAPI } from "fumadocs-openapi/server";
import { openapiPlugin } from "fumapress/plugins/openapi";

const openapi = createOpenAPI({
  proxyUrl: "/_proxy",
});

export default defineConfig({
  // ...
}).plugins(
  openapiPlugin({
    server: openapi,
    createProxy: {
      // important: set a list of allowed origins for proxied requests
      allowedOrigins: ["https://example.com"],
    },
  }),
);

Security

Always set allowedOrigins to the API hosts you trust. The proxy forwards headers and body from the playground, including cookies and Authorization. An open proxy can be abused to call arbitrary origins.

Last updated on

Mintlify

Migrate from Mintlify, powered by your docs.json file.

Orama Search

Add built-in full-text search with ZBSearch (formerly Orama).

On this page

Installation Options openapi.staticSource()Client UI Proxy Server