[!CAUTION] This plugin is forked from the original payload-oapi. I just added support to inject custom api endpoints into the OpenAPI spec.

Payload OpenAPI Plugin

Autogenerate an OpenAPI specification from your Payload CMS instance and use it for documentation or to generate client SDKs.

Roadmap

• [x] Complete description of collection CRUD endpoints
• [x] Complete description of globals CRUD endpoints
• [x] Integrated Swagger UI and Rapidoc
• [x] Authentication endpoints and specification
• [x] Preferences endpoints
• [x] Support Payload CMS 3.x
• [x] Support generating both OpenAPI 3.0 and 3.1
• [x] Custom endpoints

Installation

You can install the plugin using your preferred package manager:

• pnpm add payload-oapi
• npm install payload-oapi
• yarn add payload-oapi

Setup

1. Add the OpenAPI core plugin

To add the OpenAPI specification endpoint to your Payload app, simply import the openapi plugin and add it to your payload configuration:

import { openapi } from 'payload-oapi'

buildConfig({
  plugins: [
    openapi({ openapiVersion: '3.0', metadata: { title: 'Dev API', version: '0.0.1' } }),
  ],
  // ...
})

2. Add a documentation UI plugin (optional)

To provide a user interface for your API documentation, you can add one of the following plugins:

• scalar
• swaggerUI
• rapidoc
• redoc

Example usage:

import { openapi, scalar, swaggerUI, rapidoc, redoc } from 'payload-oapi'

// Choose one documentation UI plugins as needed
buildConfig({
  plugins: [
    openapi(/* ... */),
    // Uncomment the UI you want to use:
    scalar({ /* ...options */ }),
    // swaggerUI({ /* ...options */ }),
    // rapidoc({ /* ...options */ }),
    // redoc({ /* ...options */ }),
  ],
  // ...
})

Usage

Unless you configured it otherwise, your spec will be accessible via https://your-payload.com/api/openapi.json. If you added a documentation UI, that will be accessible via https://your-payload.com/api/docs (this is also configurable).

Custom endpoints

You can add your own custom endpoints to the generated OpenAPI specification. This is useful if you have endpoints that are not managed by Payload CMS.

To add custom endpoints, use the custom option in the openapi plugin configuration:

import { openapi } from 'payload-oapi'

buildConfig({
  plugins: [
    openapi({
      openapiVersion: '3.0',
      metadata: { title: 'Dev API', version: '0.0.1' },
      custom: {
        '/my-custom-endpoint': {
          get: {
            summary: 'My custom endpoint',
            responses: {
              '200': {
                description: 'Successful response',
                content: {
                  'application/json': {
                    schema: {
                      type: 'object',
                      properties: {
                        message: {
                          type: 'string',
                        },
                      },
                    },
                  },
                },
              },
            },
          },
        },
      },
    }),
  ],
  // ...
})