Skip to main content
@seshuk/payload-plugin-openapi builds an OpenAPI document straight from your Payload CMS config. Add it to your plugins array and you get a complete spec — collections, globals, auth, versions, and jobs — plus an interactive API reference, with zero annotation needed. The document is built lazily from the fully sanitized config, so endpoints and fields added by other plugins show up too, regardless of plugin order.

​
Key features

  • Full spec from your config — collections, globals, auth, versions, and jobs are documented automatically.
  • Native metadata — document custom endpoints and refine field schemas with Payload’s own custom.openapi key. No wrapper, no separate registry.
  • Interactive docs out of the box — mount Scalar or Swagger UI, or both.
  • Localized — descriptions resolve through your Payload i18n; the UI ships translations for 44 locales.
  • Precise filtering — control exactly which entities and operations are exposed.
  • Security marking — operations are marked public or secured by probing your access functions, with per-entity and per-operation overrides.
  • File generation — write the spec to disk for CI, schema diffs, or client codegen.
  • One option for the spec version — OpenAPI 3.0, 3.1, or 3.2 from the same config.

​
Requirements

Payload ^3.53.0 and Node.js 20 or later.

​
Where to go next

Quick start

Install the plugin and get a live spec and docs UI in one config change.

Configuration

Every plugin option, from metadata to caching and extensions.

Docs UI

Serve Scalar or Swagger UI, and pass configuration through to either.

Filters

Choose which entities and operations end up in the spec.

Security marking

How operations are marked public or secured, and how to override it.

Custom endpoints

Document your own endpoints with a plain OpenAPI Operation Object.

CLI generation

Write the spec to a file with payload openapi:generate.

Examples

Copy-ready configurations for common setups.