Publishing documentation in Postman - Framework Patterns

Framework Mode - Publishing documentation

Folder Structure for Postman Documentation Publishing

postman-project/
├── collections/
│   └── api-collection.json       # Postman collection file with API requests
├── environments/
│   ├── dev.postman_environment.json  # Environment variables for dev
│   └── prod.postman_environment.json # Environment variables for prod
├── documentation/
│   └── published-docs/            # Folder for exported or generated docs
├── scripts/
│   ├── pre-request-scripts.js     # Optional scripts for requests
│   └── test-scripts.js            # Optional test scripts
├── postman.config.json            # Configuration for Postman CLI or Newman
└── README.md                      # Project overview and publishing instructions
    

Test Framework Layers for Postman Documentation Publishing

• Collections Layer: Contains API requests grouped logically. This is the source for documentation.
• Environment Layer: Holds environment-specific variables to run requests in different setups.
• Scripts Layer: Contains pre-request and test scripts to automate checks and setup.
• Documentation Layer: Stores generated or exported documentation files ready for publishing.
• Configuration Layer: Holds config files for Postman CLI tools or Newman to automate runs and doc generation.

Configuration Patterns for Publishing Documentation

• Environment Management: Use separate environment files for dev, staging, and prod to keep variables organized.
• Collection Versioning: Maintain versions of collections to track API changes and update docs accordingly.
• Postman CLI / Newman Config: Use postman.config.json or Newman CLI commands to automate collection runs and generate documentation.
• Documentation Export Settings: Configure export format (HTML, Markdown) and location in the documentation/published-docs folder.
• Credentials Handling: Store sensitive data in environment variables, never hardcode in collections or scripts.

Test Reporting and CI/CD Integration

• Automated Doc Generation: Integrate Newman or Postman CLI in CI pipelines (GitHub Actions, Jenkins) to generate docs on collection updates.
• Publish to Web: Use Postman public documentation or export HTML/Markdown to host on company docs site or GitHub Pages.
• Test Run Reports: Capture test results from Newman runs and attach to CI reports for visibility.
• Version Control: Store collections, environments, and docs in Git to track changes and enable rollback.

Best Practices for Publishing Documentation in Postman

1. Keep Collections Clean and Organized: Group requests logically and name them clearly for easy understanding.
2. Use Environment Variables: Avoid hardcoding values; use environments to switch contexts easily.
3. Automate Documentation Generation: Use Postman CLI or Newman in CI to keep docs up-to-date without manual effort.
4. Secure Sensitive Data: Never expose credentials in collections or public docs; use environment variables and secrets management.
5. Version Your Collections: Track API changes and update docs accordingly to avoid confusion.

Self Check

Where in this folder structure would you add a new environment file for testing the API in a staging environment?

Key Result

Organize Postman collections, environments, scripts, and configs to automate and publish up-to-date API documentation.