Publishing documentation in Postman - Build an Automation Script

Publish API documentation in Postman

Preconditions (2)

Step 1: Open Postman application or web version

Step 2: Navigate to the Collections tab

Step 3: Select the collection to publish

Step 4: Click on the 'Publish Docs' button or option

Step 5: In the Publish Documentation window, verify the collection name and description

Step 6: Choose the environment if applicable

Step 7: Click the 'Publish' button

Step 8: Copy the generated documentation URL

Step 9: Open the URL in a browser to verify the documentation is accessible

✅ Expected Result: The API documentation is published successfully and accessible via the generated URL, showing the collection details and endpoints.

Automation Requirements - Postman API with Newman and Node.js

Assertions Needed:

Verify the collection exists before publishing

Verify the publish API call returns success status

Verify the documentation URL is returned and is valid

Verify the documentation URL is accessible (HTTP 200 response)

Best Practices:

Use Postman API to automate collection publishing

Use Newman or HTTP client to verify documentation URL accessibility

Use explicit checks for API responses and status codes

Handle authentication securely using environment variables

Automated Solution

Postman

import fetch from 'node-fetch';
import assert from 'assert';

// Environment variables for security
const POSTMAN_API_KEY = process.env.POSTMAN_API_KEY;
const COLLECTION_UID = process.env.COLLECTION_UID;

async function publishDocumentation() {
  // Step 1: Verify collection exists
  const collectionResponse = await fetch(`https://api.getpostman.com/collections/${COLLECTION_UID}`, {
    headers: { 'X-Api-Key': POSTMAN_API_KEY }
  });
  assert.strictEqual(collectionResponse.status, 200, 'Collection not found');

  // Step 2: Publish documentation via Postman API
  const publishResponse = await fetch(`https://api.getpostman.com/documentation/collections/${COLLECTION_UID}/publish`, {
    method: 'POST',
    headers: {
      'X-Api-Key': POSTMAN_API_KEY,
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({}) // No body needed for publish
  });
  assert.strictEqual(publishResponse.status, 200, 'Failed to publish documentation');

  const publishData = await publishResponse.json();
  const docUrl = publishData.documentation?.url;
  assert.ok(docUrl, 'Documentation URL missing');

  // Step 3: Verify documentation URL is accessible
  const docPageResponse = await fetch(docUrl);
  assert.strictEqual(docPageResponse.status, 200, 'Documentation URL not accessible');

  console.log(`Documentation published successfully: ${docUrl}`);
}

publishDocumentation().catch(err => {
  console.error('Test failed:', err.message);
  process.exit(1);
});

This script automates publishing Postman documentation using the Postman API.

First, it checks if the collection exists by calling the collections endpoint with the collection UID.

Then, it sends a POST request to the documentation publish endpoint to publish the docs.

It asserts the response status codes to ensure success at each step.

Next, it extracts the documentation URL from the response and verifies that the URL is accessible by checking for HTTP 200 status.

Environment variables are used to keep the API key and collection UID secure and configurable.

This approach uses explicit assertions and clear error messages to help identify failures.

Common Mistakes - 4 Pitfalls

Hardcoding API keys directly in the script

Not checking HTTP response status codes before proceeding

Assuming the documentation URL is always present without validation

Not verifying the documentation URL accessibility after publishing

Bonus Challenge

Now add data-driven testing to publish documentation for 3 different collections using their UIDs

Show Hint