Serve a pre-generated spec

By default the plugin both registers the openapi:generate CLI and serves the spec at /api/openapi.json. If you only want the file — generated at build time, hosted like any other static asset — turn the runtime endpoint off with serve: false.

Even with the default runtime endpoint, you are not re-generating on every request. With cache: true (the default) the document is built once on first hit and reused for the life of the process — only the server URL is refreshed per request. See Caching. serve: false is for when you want no runtime endpoint at all, not merely to avoid rebuild cost.

Turn off the runtime endpoint

payload.config.ts

import { openapi } from '@seshuk/payload-plugin-openapi'
import { buildConfig } from 'payload'

export default buildConfig({
  plugins: [
    openapi({
      metadata: { title: 'My API', version: '1.0.0' },
      serve: false, // register the CLI generator only; nothing is served over HTTP
    }),
  ],
})

With serve: false the plugin mounts neither the spec endpoint nor the interactive-auth endpoint.

The plugin still must stay in your plugins array. That call is what registers the openapi:generate bin script and stashes the resolved options it reads — remove it and the CLI stops working too.

Generate into your static assets

Write the file wherever your app serves static files — public/ in a Next.js project:

payload openapi:generate --server https://api.example.com --out ./public/openapi.json

Pass --server explicitly: a file on disk has no request to read the Host header from, so the base URL must come from you (see the CLI reference). Now public/openapi.json is served at /openapi.json like any other static file — through Next.js, a CDN, nginx, or committed to the repo. There is no per-request work and no way to hit a stale or unauthenticated spec at runtime.

Point the docs UI at the file

The docs UI plugins load the spec from a URL, and that URL does not have to be the plugin’s own endpoint. Point specEndpoint at your static file and the UI renders it directly:

payload.config.ts

import { openapi, scalar } from '@seshuk/payload-plugin-openapi'

plugins: [
  openapi({ metadata: { title: 'My API', version: '1.0.0' }, serve: false }),
  scalar({ specEndpoint: '/openapi.json' }), // loads public/openapi.json
]

The same works for swaggerUi(). See Docs UI for the renderer options.

Multiple languages

Generate one file per supported language with --lang all:

payload openapi:generate --server https://api.example.com --lang all
# → openapi.en.json, openapi.ru.json, …

Move the files into public/ and wire a language switcher exactly as in Internationalization — just point Scalar’s sources at the static files instead of the runtime endpoint:

payload.config.ts

scalar({
  configuration: {
    sources: [
      { title: 'English', url: '/openapi.en.json', default: true },
      { title: 'Русский', url: '/openapi.ru.json' },
    ],
  },
})

Documentation

Configuration

CLI

Guides

Reference

Turn off the runtime endpoint

Generate into your static assets

Point the docs UI at the file

Multiple languages

See also

​Turn off the runtime endpoint

​Generate into your static assets

​Point the docs UI at the file

​Multiple languages

​See also

Turn off the runtime endpoint

Generate into your static assets

Point the docs UI at the file

Multiple languages

See also