adding examples

packages/openapi/CHANGELOG.md

@@ -1,3 +1,7 @@
+## 1.4.0
+
+- Support for examples of collections and globals
+
 ## 1.3.0
 
 - Added detailed documentation of custom endpoints, including summary, description, success and alternative response schemas and query parameters.

packages/openapi/README.md

@@ -222,6 +222,62 @@ Response schemas can be defined as openapi schema objects or as string, referenc
 
 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.
+
+This can be either a single example:
+
+```ts
+import { CollectionConfig } from 'payload/types';
+
+const Categories: CollectionConfig = {
+  slug: 'categories',
+  custom: {
+    openapi: {
+      example: {
+        name: 'Example Category',
+        archived: false,
+      },
+    },
+  },
+  // ... Rest of collection config
+};
+```
+
+Or multiple examples
+
+```ts
+import { CollectionConfig } from 'payload/types';
+
+const Categories: CollectionConfig = {
+  slug: 'categories',
+  custom: {
+    openapi: {
+      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](#extend-the-openapi-document).
+
 ## 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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "payload-openapi",
-  "version": "1.3.0",
+  "version": "1.4.0",
   "description": "Create openapi documentation for your payload cms",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",

packages/openapi/src/config-extensions/examples.ts

@@ -0,0 +1,10 @@
+export interface Example<T = any> {
+  example?: T;
+  examples?: Record<
+    string,
+    {
+      value: T;
+      summary?: string;
+    }
+  >;
+}

packages/openapi/src/config-extensions/index.ts

@@ -1 +1,3 @@
 export { defineEndpoint, getEndpointDocumentation, EndpointDocumentation } from './custom-endpoint';
+
+export { Example } from './examples';

packages/openapi/src/index.ts

@@ -5,4 +5,4 @@ export type { RawOptions as Options } from './options';
 export { createDocument };
 export default createDocument;
 
-export { defineEndpoint, EndpointDocumentation } from './config-extensions/custom-endpoint';
+export { defineEndpoint, EndpointDocumentation, Example } from './config-extensions';

packages/openapi/src/payload-config/routes/collection/main-routes.ts

@@ -125,10 +125,11 @@ export const getMainRoutes = async (
   };
 
   const { schema, fieldDefinitions } = await entityToSchema(payloadConfig, collection);
+  const { example, examples } = collection.custom?.openapi || {};
 
   const components: OpenAPIV3.ComponentsObject = {
     schemas: {
-      [schemaName]: schema,
+      [schemaName]: { ...schema, ...{ example, examples } },
       ...includeIfAvailable(collection, 'read', {
         [pluralSchemaName]: createPaginatedDocumentSchema(schemaName, plural),
       }),

packages/openapi/src/payload-config/routes/global/index.ts

@@ -44,10 +44,11 @@ export const getGlobalRoutes = async (
   };
 
   const { schema, fieldDefinitions } = await entityToSchema(payloadConfig, global);
+  const { example, examples } = global.custom?.openapi || {};
 
   const components: OpenAPIV3.ComponentsObject = {
     schemas: {
-      [schemaName]: schema,
+      [schemaName]: { ...schema, ...{ example, examples } },
       [`${schemaName}UpsertConfirmation`]: createUpsertConfirmationSchema(schemaName, singleItem),
       ...fieldDefinitions,
     },

packages/swagger/CHANGELOG.md

@@ -1,3 +1,7 @@
+## 1.4.0
+
+- Support for examples of collections and globals
+
 ## 1.3.1
 
 - Fix issue with import of `defineEndpoint` in webpack

packages/swagger/README.md

@@ -249,6 +249,62 @@ Response schemas can be defined as openapi schema objects or as string, referenc
 
 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.
+
+This can be either a single example:
+
+```ts
+import { CollectionConfig } from 'payload/types';
+
+const Categories: CollectionConfig = {
+  slug: 'categories',
+  custom: {
+    openapi: {
+      example: {
+        name: 'Example Category',
+        archived: false,
+      },
+    },
+  },
+  // ... Rest of collection config
+};
+```
+
+Or multiple examples
+
+```ts
+import { CollectionConfig } from 'payload/types';
+
+const Categories: CollectionConfig = {
+  slug: 'categories',
+  custom: {
+    openapi: {
+      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](#extend-the-openapi-document).
+
 ## 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/swagger/package.json

@@ -1,6 +1,6 @@
 {
   "name": "payload-swagger",
-  "version": "1.3.1",
+  "version": "1.4.0",
   "description": "Swagger plugin for payload cms",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
@@ -13,7 +13,7 @@
     "typecheck": "tsc --noEmit"
   },
   "dependencies": {
-    "payload-openapi": "^1.3.0",
+    "payload-openapi": "^1.4.0",
     "swagger-ui-express": "^4.6.2"
   },
   "peerDependencies": {

packages/swagger/src/index.ts

@@ -5,4 +5,4 @@ export type { Options } from './types';
 export { swagger };
 export default swagger;
 
-export { defineEndpoint, EndpointDocumentation } from './openapi';
+export { defineEndpoint, EndpointDocumentation, Example } from './openapi';

packages/swagger/src/openapi.ts

@@ -1,7 +1,7 @@
 import { Endpoint } from 'payload/config';
 
 import type { EndpointDocumentation } from 'payload-openapi';
-export type { EndpointDocumentation } from 'payload-openapi';
+export type { EndpointDocumentation, Example } from 'payload-openapi';
 
 type DocumentedEndpoint = Endpoint & EndpointDocumentation;
 

packages/testbed/src/collections/Categories.ts

@@ -42,6 +42,14 @@ const Categories: CollectionConfig = {
       },
     },
   ],
+  custom: {
+    openapi: {
+      example: {
+        name: 'Example Category',
+        archived: false,
+      },
+    },
+  },
 };
 
 export default Categories;

packages/testbed/src/collections/Posts.ts

@@ -101,7 +101,7 @@ const Posts: CollectionConfig = {
         },
       },
       handler: async (req, res) => {
-        const { docs } = await req.payload.find<any>({
+        const { docs } = await req.payload.find({
           collection: 'categories',
           where: { name: { equals: req.params.category } },
         });
@@ -110,7 +110,7 @@ const Posts: CollectionConfig = {
         }
 
         const { limit, page, sort } = req.query;
-        const posts = await req.payload.find<any>({
+        const posts = await req.payload.find({
           collection: 'posts',
           where: { category: { equals: (docs[0] as any).id } },
           limit: limit && Number(limit),