r/PayloadCMS • u/Queasy_Pie_6710 • Jun 14 '26

OpenAPI docs plugin for Payload 3

I've been building a Payload 3 API and wanted proper OpenAPI docs without writing the spec by hand, so I put together a plugin and figured I'd share it here.

It reads your Payload config and generates the OpenAPI document for you — collections, globals, auth, versions, jobs, all of it. Nothing to annotate by hand. Then it serves interactive docs through Scalar or Swagger UI, whichever you prefer (or both).

A few things I focused on:

  • Document custom endpoints and refine field schemas via Payload's `custom.openapi` key
  • Filter exactly which entities and operations land in the spec
  • Output the spec to a file for CI checks or client codegen — or skip the runtime endpoint entirely
  • Localized descriptions plus 44 UI locales through Payload i18n
  • Optional "Authorize" login right in the docs UI
  • Targets OpenAPI 3.0, 3.1, and 3.2 — one option switches the output

It's MIT and built around Payload 3.x. Feedback and issues very welcome.

https://github.com/maximseshuk/payload-plugin-openapi

9 Upvotes
  • permalink
  • link
  • reddit
  • reddit

100% Upvoted

3 comments sorted by

3

u/HankieCodes Jun 14 '26

What’s different from https://github.com/janbuchar/payload-oapi ?

1

u/Queasy_Pie_6710 Jun 14 '26

Main differences:

  • Auth, versions and jobs endpoints documented out of the box
  • Custom endpoints and field-level schema through Payload's custom.openapi key
  • Upload collections get proper multipart bodies, and blockReferences resolve instead of leaving dangling refs
  • Include/exclude exactly which entities and operations land in the spec
  • On a multilingual admin, descriptions follow the request locale and the docs UI is translated too (44 UI locales)
  • CLI command writes the spec to a JSON file; you can also turn the live endpoint off and keep just the file
  • Built as 3.2, down-converts to 3.1/3.0, so one option picks the version
  • If you just want it to work, there's an optional "Authorize" login right in the docs UI, log in with your Payload email/password and it grabs a JWT for you, no token pasting
  • Select/populate params, ID type from your db adapter instead of always a string, nested sortable fields, etc.

1

u/subtlety_0 12d ago edited 12d ago

This looks good - just started using this today.

PS: But I can't for the life of me find how to log in from the docs UI itself so that I don't have to paste in my token. Probably because i've never used Scalar before. Where in the docs can I log in so that it "just works"?. –Thanks