documentation

packages/openapi/CHANGELOG.md

@@ -1,3 +1,7 @@
+## 1.3.0
+
+- Added detailed documentation of custom endpoints, including summary, description, success and alternative response schemas and query parameters.
+
 ## 1.2.1
 
 - Added `unsupported Payload version` schema to be generated if user attempt to create a schema with a Payload version that has known schema generation issues

packages/openapi/README.md

@@ -146,6 +146,82 @@ const Media: CollectionConfig = {
 };
 ```
 
+## Documentation of custom endpoints
+
+Custom endpoints on all levels can be fully documented, either by using the `defineEndpoint` helper:
+
+```ts
+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:
+
+```ts
+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`.
+
 ## 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.

packages/openapi/src/config-extensions/custom-endpoint.ts

@@ -6,18 +6,20 @@ export interface EndpointDocumentation {
   description: string;
   responseSchema: OpenAPIV3.SchemaObject | string;
   errorResponseSchemas?: Record<number, OpenAPIV3.SchemaObject | string>;
-  queryParamters?: {
-    name: string;
-    description?: string;
-    required?: boolean;
-    schema: OpenAPIV3.SchemaObject | string;
-  }[];
+  queryParameters?: Record<
+    string,
+    {
+      description?: string;
+      required?: boolean;
+      schema: OpenAPIV3.SchemaObject | string;
+    }
+  >;
 }
 
 type DocumentedEndpoint = Endpoint & EndpointDocumentation;
 
 export function defineEndpoint(endpoint: DocumentedEndpoint): Endpoint {
-  const { summary, description, responseSchema, errorResponseSchemas, queryParamters, custom, ...rest } = endpoint;
+  const { summary, description, responseSchema, errorResponseSchemas, queryParameters, custom, ...rest } = endpoint;
   return {
     ...rest,
     custom: {
@@ -27,7 +29,7 @@ export function defineEndpoint(endpoint: DocumentedEndpoint): Endpoint {
         description,
         responseSchema,
         errorResponseSchemas,
-        queryParamters,
+        queryParameters,
       },
     },
   };

packages/openapi/src/payload-config/routes/custom-paths.ts

@@ -4,6 +4,7 @@ import { Endpoint, SanitizedConfig } from 'payload/config';
 import { SanitizedCollectionConfig, SanitizedGlobalConfig } from 'payload/types';
 import { createResponse } from '../../schemas';
 import { getEndpointDocumentation } from '../../config-extensions';
+import { objectEntries } from 'ts-powertools';
 
 type Config = SanitizedConfig | SanitizedCollectionConfig | SanitizedGlobalConfig;
 type ConfigType = 'payload' | 'global' | 'collection';
@@ -88,13 +89,15 @@ export const getCustomPaths = (config: Config, type: ConfigType): Pick<Required<
   const tags = getTags(config, type);
 
   for (const endpoint of config.endpoints.filter(endpoint => isRelevant(endpoint, type))) {
+    if (endpoint.custom?.openapi === false) continue;
+
     const { path, parameters = [] } = getPath(basePath, endpoint.path);
     const {
       summary,
       description = 'custom operation',
       responseSchema = { type: 'object' },
       errorResponseSchemas = {},
-      queryParamters = [],
+      queryParameters = {},
     } = getEndpointDocumentation(endpoint) || {};
     if (!paths[path]) paths[path] = {};
 
@@ -104,7 +107,7 @@ export const getCustomPaths = (config: Config, type: ConfigType): Pick<Required<
       tags,
       parameters: [
         ...parameters,
-        ...queryParamters.map(({ name, description, required, schema }) => ({
+        ...objectEntries(queryParameters).map(([name, { description, required, schema }]) => ({
           name,
           description: description || name,
           in: 'query',

packages/openapi/test/integration/custom-endpoints.config.ts

@@ -24,6 +24,14 @@ const config: Config = {
             res.json(value);
           },
         }),
+        {
+          path: '/hidden',
+          method: 'get',
+          handler: () => {
+            /* do nothing */
+          },
+          custom: { openapi: false },
+        },
       ],
     },
   ],

packages/swagger/CHANGELOG.md

@@ -1,3 +1,7 @@
+## 1.3.0
+
+- Support for custom endpoint documentation of payload-openapi
+
 ## 1.2.1
 
 - Adds fallback document if openapi document generation fails

packages/swagger/README.md

@@ -173,6 +173,82 @@ const Media: CollectionConfig = {
 };
 ```
 
+## Documentation of custom endpoints
+
+Custom endpoints on all levels can be fully documented, either by using the `defineEndpoint` helper:
+
+```ts
+import { CollectionConfig } from 'payload/types';
+import { defineEndpoint } from 'payload-swagger';
+
+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:
+
+```ts
+import { CollectionConfig } from 'payload/types';
+import type { EndpointDocumentation } from 'payload-swagger';
+
+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`.
+
 ## 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.

packages/testbed/src/collections/Posts.ts

@@ -86,23 +86,20 @@ const Posts: CollectionConfig = {
       errorResponseSchemas: {
         404: 'error',
       },
-      queryParamters: [
-        {
-          name: 'limit',
+      queryParameters: {
+        limit: {
           description: 'limit the number of posts returned',
           schema: { type: 'number' },
         },
-        {
-          name: 'page',
+        page: {
           description: 'the page number to return',
           schema: { type: 'number' },
         },
-        {
-          name: 'sort',
+        sort: {
           description: 'the field to sort by',
           schema: { type: 'string' },
         },
-      ],
+      },
       handler: async (req, res) => {
         const { docs } = await req.payload.find<any>({
           collection: 'categories',