Description formatting (Markdown) in Postman - Framework Patterns

Framework Mode - Description formatting (Markdown)

Folder Structure

PostmanCollectionProject/
├── collections/
│   └── MyAPICollection.postman_collection.json
├── environments/
│   ├── dev.postman_environment.json
│   ├── staging.postman_environment.json
│   └── prod.postman_environment.json
├── tests/
│   └── test-scripts.js
├── docs/
│   └── README.md
└── postman.config.json

Test Framework Layers

• Collections: JSON files defining API requests, grouped logically.
• Environments: JSON files holding variables for different deployment stages.
• Test Scripts: JavaScript code inside requests or separate files for pre-request and test validations.
• Documentation: Markdown files describing API usage, test strategy, and formatting guidelines.
• Configuration: JSON or environment files controlling global settings like base URLs and authentication.

Configuration Patterns

• Environment Variables: Use environment files to store URLs, tokens, and other sensitive data per environment.
• Global Variables: For values shared across collections or environments.
• Collection Variables: Scoped to a specific collection for modularity.
• Markdown Descriptions: Use Markdown syntax in request and collection descriptions for clarity and formatting.
• Version Control: Store collections and environments in source control for traceability.

Test Reporting and CI/CD Integration

• Use Newman CLI to run Postman collections in CI pipelines (GitHub Actions, Jenkins, GitLab CI).
• Generate HTML or JSON reports from Newman runs for easy review.
• Integrate with Slack or email to notify test results automatically.
• Use environment-specific runs to validate APIs in different stages.

Best Practices

• Consistent Markdown Usage: Use headings, bullet points, code blocks, and links in descriptions for readability.
• Clear and Concise Descriptions: Explain request purpose and expected behavior simply.
• Use Variables in Descriptions: Reference environment or collection variables in descriptions to keep info dynamic.
• Keep Documentation Close: Maintain descriptions inside Postman collections to keep tests and docs together.
• Version Control Collections: Track changes and collaborate effectively.

Self Check

Where in this folder structure would you add a new Markdown file explaining how to format descriptions in Postman collections?

Key Result

Use Markdown in Postman descriptions to create clear, readable API documentation within your test collections.