Skip to main content
The plugin registers a Payload CLI command named openapi:generate. It builds the same document the runtime endpoint serves and writes it to disk — no HTTP request, no running server needed.
Writing the spec to a file is useful when you want to:
  • Commit the spec to the repo, so API changes show up in code review.
  • Diff schemas in CI and fail the build on unintended API changes.
  • Feed a client-code generator (openapi-typescript, Orval, and friends).
  • Host a static spec with no runtime endpoint at all — see Serve a pre-generated spec.
The command reads the plugin’s resolved options from your Payload config, so openapi() must be in your plugins array — even with serve: false.

​
Flags

Flags accept both --flag value and --flag=value.

​
--lang

Picks the locale used for translated titles and descriptions. Defaults to your project’s i18n.fallbackLanguage.
Pass all to write one file per language in your i18n.supportedLanguages, named openapi.<lang>.json:
When --lang all writes multiple files, the openapi.<lang>.json naming applies and --out is ignored.
See Internationalization for how language resolution works.

​
--out

Output path for a single-language run:

​
--server

Base URL written to the spec’s servers array:
A file on disk has no request, so the command does not use trustedHosts or a servers function. Without --server it uses the servers option when it is an array, then serverURL from your Payload config. With none of them, servers is empty. See Servers.
The generated spec reflects public-access marking only — it never runs per-user access checks. This matches the HTTP endpoint exactly. See Security marking.

​
CI example

Commit the spec, regenerate it in CI, and fail the job when the committed file drifts from the config:
.github/workflows/openapi.yml
The diff in the failed job output is a readable summary of what changed in your API.

​
See also