Generating documentation from collections in Postman - Build an Automation Script

Generate API documentation from a Postman collection

Preconditions (2)

Step 1: Open Postman application or web version

Step 2: Navigate to the Collections tab

Step 3: Select the desired collection to document

Step 4: Click on the '...' (three dots) menu next to the collection name

Step 5: Choose 'Publish Docs' from the dropdown menu

Step 6: In the documentation editor, verify the collection name and description

Step 7: Review the automatically generated documentation for each request

Step 8: Click 'Publish' to generate a public documentation link

Step 9: Copy the generated documentation URL

✅ Expected Result: A public documentation page is created and accessible via the copied URL, showing all requests and details from the selected collection

Automation Requirements - Postman Test Scripts and Newman CLI

Assertions Needed:

Verify the collection exists and is accessible

Verify the documentation generation command runs without errors

Verify the generated documentation URL is not empty

Verify the documentation page contains the collection name

Best Practices:

Use Newman CLI to run collection and generate documentation

Use environment variables for collection and documentation URLs

Validate outputs with assertions in test scripts

Use explicit checks for HTTP response codes when accessing documentation URL

Automated Solution

Postman

import newman from 'newman';

// Run the collection and generate documentation
newman.run({
    collection: './MyCollection.json',
    reporters: ['cli', 'html'],
    reporter: {
        html: {
            export: './docs/collection-documentation.html'
        }
    }
}, function (err, summary) {
    if (err) {
        console.error('Collection run failed:', err);
        process.exit(1);
    }
    // Check if run was successful
    const runStats = summary.run.stats;
    if (runStats.failed > 0) {
        console.error(`Test failures: ${runStats.failed}`);
        process.exit(1);
    }
    console.log('Collection run completed successfully. Documentation generated at ./docs/collection-documentation.html');
});

This script uses Newman, the command-line runner for Postman collections, to run the collection and generate an HTML report which serves as documentation.

The collection option points to the local Postman collection file.

The reporters option includes html to generate a documentation page.

The reporter.html.export option specifies the output file path for the documentation.

After running, the script checks for errors and test failures, logging appropriate messages.

This approach automates documentation generation and verifies the collection runs without errors.

Common Mistakes - 3 Pitfalls

Not specifying the collection file path correctly in Newman run

Not checking for errors or failed tests after running the collection

Assuming documentation URL is generated automatically without publishing

Bonus Challenge

Now add data-driven testing by running the collection with 3 different environment files

Show Hint