payload-openapi
v1.4.0
Published
Create openapi documentation for your payload cms
Downloads
12,940
Readme
payload-openapi
Generate openapi 3 documentation for your payload cms.
payload-openapi
documents ALL your payload openapi endpoints and includes:
- collection endpoints
- global endpoints
- custom endpoints
- authentication endpoints
- preferences endpoints
- fully typed schema definitions for all requests, parameters and responses
- authentication requirements for all your endpoints
- extension points to merge your custom openapi definitions into the schema
Alternatives:
- payload-swagger if you want to publish the openapi document with a swagger UI
- create-payload-api-docs if you want a cli version
Installation
With yarn:
yarn add payload-openapi
With npm:
npm install payload-openapi
Usage
payload-openapi
creates openAPI documents, version 3.0, as javascript object. If you need a yaml file, please use a library like yaml
to convert it.
import { createDocument } from 'payload-swagger';
import payloadConfig from '...';
const openapiDocument = createDocument(payloadConfig, {
/* see options section */
});
Extend the openAPI document
The openapi document generated by payload-openapi
includes information from the following external sources:
package.json
:payload-openapi
uses the information in the fields shown below. Inopenapi
a partial openapi document can be included;
{
"name": "my payload cms",
"version": "1.2.3",
"description": "My awesome cms",
"license": "MIT",
"openapi": {}
}
.openapi
: optional file with partial openapi document in JSON format.
The data from all these source is recursively merged into the final document.
Options
payload-openapi
has the following options:
interface Options {
/**
* By default the access functions on all collections in the config are called to determine
* the access level of the operations.
* Provide an array of collection slugs to disable this for the given collections,
* or `true` to disable for all.
*/
disableAccessAnalysis?: boolean | string[];
/**
* Exclude parts of the payload config from document generation
*/
exclude?: {
authPaths?: boolean;
authCollection?: boolean;
passwordRecovery: boolean; // default true, set to `false` to include
preferences?: boolean; // default true, set to `false` to include
custom?: boolean;
};
}
Schema names
By default the schema name is derived from the global / collection slug
. If the collection has a value for label.{singular/plural}.openapi
or the global a value for label.openapi
, that value is used instead.
import { CollectionConfig } from 'payload/types';
const Media: CollectionConfig = {
slug: 'posts',
labels: {
singular: { openapi: 'post' },
plural: { openapi: 'posts' },
},
// ... Rest of collection config
};
Descriptions
Endpoint descriptions and summaries are generated from the description
and label
/labels.{singular/plural}
fields of your globals and collections. If a multilanguage (Record<string, string>
) value is found, the order of priority for picking the language is as follows:
- docs
- en
- first value found that is a string
This makes it possible to set a custom description for the docs:
import { CollectionConfig } from 'payload/types';
const Media: CollectionConfig = {
slug: 'media',
admin: {
description: {
docs: 'Description used in openapi docs',
en: 'Description used in the admin panel',
},
},
labels: {
singular: 'Single value used everywhere',
plural: {
docs: 'Plural value used in docs',
en: 'Plural value used in admin panel',
},
},
// ... Rest of collection config
};
Documentation of custom endpoints
Custom endpoints on all levels can be fully documented, either by using the defineEndpoint
helper:
import { CollectionConfig } from 'payload/types';
import { defineEndpoint } from 'payload-openapi';
const Post: CollectionConfig = {
slug: 'posts',
endpoints: [
defineEndpoint({
summary: 'media by category',
description: 'gets the media of the given category',
path: '/category/:category',
method: 'get',
responseSchema: 'posts',
errorResponseSchemas: {
404: 'error',
},
queryParameters: {
limit: { schema: { type: 'number' } },
page: { schema: { type: 'number' } },
sort: { scema: { type: 'string' } },
},
handler: (req, res) => {
// ... handler implementation
},
}),
],
// ... Rest of collection config
};
or by setting the custom.openapi
property:
import { CollectionConfig } from 'payload/types';
import type { EndpointDocumentation } from 'payload-openapi';
const documentation: EndpointDocumentation = {
summary: 'media by category',
description: 'gets the media of the given category',
responseSchema: 'posts',
errorResponseSchemas: {
404: { type: 'object', properties: { message: { type: 'string' } }, required: ['message'] },
},
queryParameters: {
limit: { schema: { type: 'number' } },
page: { schema: { type: 'number' } },
sort: { scema: { type: 'string' } },
},
};
const Post: CollectionConfig = {
slug: 'posts',
endpoints: [
{
path: '/category/:category',
method: 'get',
handler: (req, res) => {
// ... handler implementation
},
custom: {
openapi: documentation,
},
},
],
// ... Rest of collection config
};
Response schemas can be defined as openapi schema objects or as string, referencing any of the schemas defined in the schema section of the openapi document.
To exclude a custom endpoint from the documentation, set the custom.openapi
property to false
.
Adding examples
Examples can be added on collections and globals using the defineCollection
or defineGlobal
helper:
import { defineCollection } from 'payload-openapi';
const Categories = defineCollection({
slug: 'categories',
example: {
name: 'Example Category',
archived: false,
},
// ... Rest of collection config
});
Or by setting the custom.openapi
property:
import { CollectionConfig } from 'payload/types';
const Categories: CollectionConfig = {
slug: 'categories',
custom: {
openapi: {
example: {
name: 'Example Category',
archived: false,
},
},
},
// ... Rest of collection config
};
It's also possible to set multiple examples:
import { defineCollection } from 'payload-openapi';
const Categories = defineCollection({
slug: 'categories',
examples: {
active: {
value: {
name: 'Active Category',
archived: false,
},
summary: 'Example of an active category',
},
archive: {
value: {
name: 'Archived Category',
archived: true,
},
summary: 'Example of an archived category',
},
},
// ... Rest of collection config
});
Openapi supports examples at lots of different levels. To add examples add other levels, you can define theme in a separate partial openapi document, as described here.
Excluding unused endpoints
In Payload collections
and globals
have a standard set of available endpoints. In some situations you might not want to use some of these endpoints. In those situations you probably have used an access method that looks something like this: () => false;
. This blocks all traffic, but the endpoint is still part of the openapi documentation.
To also remove the endpoint from the openapi documentation, you can use payload-rbac:
import { CollectionConfig } from 'payload/types';
import { blockAll } from 'payload-rbac';
const Media: CollectionConfig: {
slug: 'media',
access: {
delete: blockAll(), // Use block all to exclude endpoint from docs
},
// ... Rest of collection config
}
Version history
See changelog