payload-oapi - GitLite

KO | EN

gitlite — search

#python #hacktoberfest #react #typescript #deep-learning #linux #macos #java #windows #vue #awesome-list #pytorch #security #ios

payload-oapi

(★ 123)

A Payload CMS plugin for OpenAPI (3.0, 3.1) specification generation

File Explorer

Download Latest Version (.zip)

- - check.yml
  - release.yml
- - Pages.ts
  - Pets.ts
  - Posts.ts
  - Users.ts
- - FeaturedPet.ts
- - credentials.ts
  - NextRESTClient.ts
  - testEmailAdapter.ts
- .env.example
- docker-compose.yml
- next-env.d.ts
- next.config.mjs
- payload-types.ts
- payload.config.ts
- seed.ts
- server.ts
- tsconfig.json
- - generators.ts
  - naming.ts
  - securitySchemes.ts
- - fields.ts
  - filters.ts
  - objects.ts
  - strings.ts
- index.ts
- openapiPlugin.ts
- rapidocPlugin.ts
- redocPlugin.ts
- requestHandlers.ts
- scalarPlugin.ts
- swaggerUIPlugin.ts
- types.ts
- - openapi-generators.test.ts.snap
- openapi-generators.test.ts
- tsconfig.json
.editorconfig
.gitignore
biome.json
CHANGELOG.md
cliff.toml
LICENSE.md
package.json
README.md
tsconfig.json
yarn.lock

// repository documentation

Was this content helpful?

★ 0 (0 ratings)

# Payload OpenAPI Plugin

[![npm version](https://badge.fury.io/js/payload-oapi.svg)](https://www.npmjs.com/package/payload-oapi)

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] Collection and global filtering
- [ ] 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:

```typescript
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`](https://github.com/scalar/scalar)
- [`swaggerUI`](https://swagger.io/tools/swagger-ui/)
- [`rapidoc`](https://mrin9.github.io/RapiDoc/)
- [`redoc`](https://github.com/Redocly/redoc)

Example usage:

```typescript
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 */ }),
  ],
  // ...
})
```

## 3. Filter collections and globals (optional)

Control which collections and globals appear in the OpenAPI spec using the `filters` option:

- `includeCollections` / `excludeCollections` — filter collections by slug
- `includeGlobals` / `excludeGlobals` — filter globals by slug
- `hideInternalCollections` — exclude `payload-*` collections

Example:

```typescript
openapi({
  openapiVersion: '3.0',
  metadata: { title: 'Dev API', version: '0.0.1' },
  filters: {
    includeCollections: ['posts', 'categories'],
    excludeGlobals: ['footer'],
    hideInternalCollections: true,
  },
})
```

# 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).