Here's a complete README.md for your PayloadCMS plugin that generates a Postman collection automatically:

📬 PayloadCMS Postman Docs Plugin

Automatically generate a full-featured Postman collection for your PayloadCMS API, including authentication, CRUD endpoints, globals, and custom routes. Great for rapid API documentation, testing, and client handoffs.

✨ Features

• 🔐 Auth endpoints for all auth-enabled collections
• 📦 CRUD endpoints for your Payload collections
• 🌍 Support for Payload Globals
• 🧪 Built-in test scripts for response validation
• 🧪 Optional sample data generation
• 🧰 Utility endpoints (/api/health, /api/access)
• 🔧 Custom endpoints support
• 💻 Admin panel button to download the collection
• 🌐 Configurable base URL, token var, and collection name

📦 Installation

npm install your-payload-postman-plugin
# or
yarn add your-payload-postman-plugin

🔧 Usage

// payload.config.ts
import { PostmanDocsPlugin } from './plugins/payload-plugin-postman-docs'

export default buildConfig({
  // ... your config
  plugins: [
    PostmanDocsPlugin({
      baseURL: 'http://localhost:3000',
      collectionName: 'My API Docs',
      includeAuth: true,
      generateSampleData: true,
      collections: ['users', 'posts'], // optional
      excludeCollections: ['logs'], // optional
      customEndpoints: [
        {
          name: 'Trigger Sync Job',
          path: '/api/trigger-sync',
          method: 'POST',
          description: 'Manually trigger the data sync job.',
        },
      ],
    }),
  ],
})

📁 Endpoints

| Method | Path | Description | | ------ | -------------------------- | ---------------------------------------------------- | | GET | /postman-collection | Returns the generated Postman collection (JSON) | | GET | /postman-collection/info | Returns metadata about collections and plugin config |

🧪 Example Postman Collection Structure

• Authentication/
• Users/ (or your collection name)
• Globals/
• Custom Endpoints/
• Utility Endpoints/

Each collection includes:

• Get all (with query params)
• Get by ID
• Create
• Update (PUT)
• Partial Update (PATCH)
• Delete

Auth collections also include:

• Login
• Logout
• Me
• Refresh Token
• Forgot Password

🛠️ Plugin Options

| Option | Type | Default | Description | | -------------------- | -------------------------------------------- | -------------------------------------------------------------------- | ---------------------------------------- | | authCollections | string[] | [] | Only include these collections for auth | | baseURL | string | process.env.PAYLOAD_PUBLIC_SERVER_URL or 'http://localhost:3000' | Base URL used in Postman | | collectionName | string | 'PayloadCMS API Collection' | Name of the Postman collection | | collections | string[] | undefined | Only include these collections | | excludeCollections | string[] | [] | Exclude these collections from output | | customEndpoints | Array<{ name, method, path, description }> | [] | Add your own endpoints to the collection | | enabled | boolean | true | Enable or disable the plugin | | generateSampleData | boolean | true | Auto-generate sample payloads | | includeAuth | boolean | true | Include auth-related endpoints | | includeGlobals | boolean | true | Include global config endpoints | | includeValidation | boolean | true | Add test scripts to Postman requests |

🧩 UI Integration

This plugin adds a "Postman Collection" button to your Payload Admin sidebar. When clicked, it triggers a download of the generated collection.

The UI component must be available at: ./components/PostmanDocsButton.tsx

You can use a simple example like:

import React from 'react'
import { useAuth } from 'payload/components/utilities'
import { Button } from 'payload/components/elements'

export const PostmanDocsButton = () => {
  const { user } = useAuth()

  if (!user) return null

  const handleDownload = async () => {
    const response = await fetch('/postman-collection')
    const blob = await response.blob()
    const url = URL.createObjectURL(blob)

    const a = document.createElement('a')
    a.href = url
    a.download = 'postman-collection.json'
    a.click()
  }

  return (
    <Button onClick={handleDownload} className="btn">
      Download Postman Collection
    </Button>
  )
}

🧪 Sample Data Generation

When generateSampleData: true is enabled, the plugin auto-generates request bodies based on your field types.

Supported field types:

• text, textarea, number, checkbox
• email, date, code, json
• radio, select, richText
• group, array, blocks
• relationship, upload, point

📜 License

MIT

🙏 Contributions

Feel free to open issues or submit PRs to improve this plugin. Feedback is welcome!

Let me know if you want:

• A working example repo
• A version published to npm
• A section on how to test with Postman environments or CI