Quick start

Install

npm install @seshuk/payload-plugin-openapi@beta

pnpm add @seshuk/payload-plugin-openapi@beta

yarn add @seshuk/payload-plugin-openapi@beta

Requires Payload 4.0.0-canary.38, Next.js 16.4 or later and Node.js 24.15 or later. v1 is in beta under the beta npm tag, and Payload 4 is published under canary. For Payload 3, use the 0.x versions.

Add the plugin

Add openapi() for the spec and scalar() for the docs UI:

payload.config.ts

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

export default buildConfig({
  // ...
  plugins: [
    openapi({
      info: {
        title: 'My API',
        version: '1.0.0',
      },
    }),
    scalar(),
  ],
})

info.title and info.version are required. The plugin throws on boot if either is missing.

Open the docs

Two endpoints are now live:

GET /api/openapi.json — the generated OpenAPI document
GET /api/docs — interactive API reference (Scalar)

Both are mounted under your Payload API route (routes.api, /api by default), since the plugin registers them as Payload endpoints. The path options you pass to openapi(), scalar() and swaggerUi() are relative to that route.Prefer Swagger UI? Swap scalar() for swaggerUi() — or mount both on different paths. See Docs UI.

Next steps

Configuration overview — every plugin option
Filters — choose which entities and operations are documented
Security marking — how operations get their public/secured padlock
Custom endpoints — document your own endpoints with custom.openapi
CLI generation — write the spec to a file for CI or codegen
Examples — complete configurations for common setups

Documentation

Configuration

CLI

Guides

Reference

Next steps

​Next steps

Next steps