README.md

Payload OpenAPI Plugin

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

Roadmap

• Complete description of collection CRUD endpoints
• Complete description of globals CRUD endpoints
• Integrated Swagger UI and Rapidoc
• Authentication endpoints and specification
• Preferences endpoints
• Support Payload CMS 3.x
• Support generating both OpenAPI 3.0 and 3.1
• 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' } }),
  ],
  // ...
})

To include custom endpoints you need to provide a documentation under the custom openapi property of the endpoint.

import type { CustomEndpointDocumentation } from 'payload-oapi'
import type { CollectionConfig } from 'payload'

export const Pets: CollectionConfig = {
  slug: 'pets',
  // ...
  endpoints: [
    {
      // ...
      custom: {
        openapi: {
          summary: 'Delete pets by status',
          description: 'Delete pets by status',
          parameters: [
            {
              name: 'status',
              in: 'path',
              required: true,
              schema: {
                type: 'string',
                enum: ['available', 'pending', 'sold'],
              },
            },
          ],
          responses: {
            200: {
              type: 'object',
              properties: {
                message: {
                  type: 'string',
                  description: 'A message indicating the result of the operation',
                },
              },
            },
          },
        } as CustomEndpointDocumentation<'3.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).