Quick start

Install

npm install @seshuk/payload-plugin-openapi

pnpm add @seshuk/payload-plugin-openapi

yarn add @seshuk/payload-plugin-openapi

Requires Payload ^3.53.0 and Node.js 20 or later.

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({
      metadata: {
        title: 'My API',
        version: '1.0.0',
      },
    }),
    scalar(),
  ],
})

metadata.title and metadata.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 and specEndpoint options you pass 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

⌘I

Documentation

Configuration

CLI

Guides

Reference

Next steps

​Next steps

Next steps