Request descriptions and documentation in Postman - Practice Problems & Coding Challenges

Challenge - 5 Problems

🧠 Conceptual

intermediate

Purpose of Request Descriptions in Postman

Why is it important to add descriptions to API requests in Postman collections?

A To disable the request from running accidentally.

B To increase the size of the collection file for better security.

C To automatically generate API keys for authentication.

D To provide clear explanations for each request, helping team members understand the API's purpose and usage.

💡 Hint

Think about how documentation helps others who use or maintain the API.

Descriptions clarify what each request does, making it easier for team members or users to understand and use the API correctly.

❓ Predict Output

intermediate

Output of Missing Description in Postman Documentation

What will be the visible effect in Postman documentation if a request has no description?

A Postman will show an error and prevent documentation generation.

B The request will be hidden from the documentation automatically.

C The request will appear without any explanation or notes in the generated documentation.

D Postman will add a default description saying 'No description provided'.

💡 Hint

Consider what happens when no extra information is given for a request.

Requests without descriptions appear in the documentation but lack explanatory text, which can confuse users.

❓ assertion

advanced

Valid Assertion for Checking Request Description Presence

Which Postman test script assertion correctly verifies that the current request has a non-empty description?

Postman

pm.test('Request has description', () => {
    // assertion here
});

A pm.expect(pm.request.description).to.be.a('string').and.not.empty;

B pm.expect(pm.request.description).to.equal(null);

C pm.expect(pm.request.description).to.be.undefined;

D pm.expect(pm.request.description.length).to.be.lessThan(0);

💡 Hint

Check for a string type and that it is not empty.

Option A correctly asserts that the description exists as a non-empty string. Other options check for null, undefined, or invalid length.

🔧 Debug

advanced

Debugging Missing Description in Generated Documentation

You notice that a request's description is not showing up in the published Postman documentation, even though you added it in the request editor. What is the most likely cause?

A The description was added in the request's pre-request script instead of the description field.

B The description field was saved but the collection was not updated or synced before publishing.

C The request name is too long, so the description is hidden automatically.

D Postman does not support descriptions in documentation for requests.

💡 Hint

Think about how changes are saved and published in Postman collections.

Descriptions must be saved and the collection updated before publishing. If not synced, the old version without description is published.

❓ framework

expert

Best Practice for Documenting Request Parameters in Postman

Which approach best ensures that request parameters are clearly documented and visible in Postman-generated API documentation?

A Use the request description field to list and explain all parameters with examples and expected values.

B Only rely on parameter names in the URL or body without additional explanation.

C Add parameter details only in the test scripts section for internal use.

D Write parameter explanations in a separate external document and link it in the collection description.

💡 Hint

Consider where users look for parameter details in Postman documentation.

Including parameter details in the request description ensures they appear directly in the documentation, making it easy for users to understand and use the API.