Request descriptions and documentation in Postman - Build an Automation Script

Add descriptions to API requests and verify documentation

Preconditions (2)

Step 1: Open the Postman application

Step 2: Navigate to the existing collection

Step 3: Select an API request in the collection

Step 4: Click on the 'Description' tab or field for the request

Step 5: Enter a clear description explaining the request purpose and parameters

Step 6: Save the request

Step 7: Open the collection documentation view

Step 8: Verify that the request description appears correctly in the documentation

✅ Expected Result: The request description is saved and displayed correctly in the collection documentation

Automation Requirements - Postman Test Scripts (JavaScript)

Assertions Needed:

Verify the request description field is not empty

Verify the description text matches the expected content

Best Practices:

Use descriptive and clear text for request descriptions

Keep descriptions concise but informative

Use Postman scripting to validate request metadata

Maintain documentation updated with request changes

Automated Solution

Postman

pm.test('Request description is present and correct', () => {
    const description = pm.request.description?.content || '';
    pm.expect(description).to.not.be.empty;
    pm.expect(description).to.include('purpose'); // Replace 'purpose' with expected keyword in description
});

This test script runs after the request execution in Postman.

It accesses the request's description content using pm.request.description.content.

First, it checks that the description is not empty to ensure documentation exists.

Then, it verifies the description includes an expected keyword or phrase to confirm correctness.

This helps keep request documentation accurate and visible in Postman collections.

Common Mistakes - 3 Pitfalls

Not adding any description to the request

Using vague or overly technical language in descriptions

Not verifying descriptions via automated tests

Bonus Challenge

Now add automated tests to verify descriptions for all requests in the collection

Show Hint