Postman Collection Generator Laravel Package

Getting Started

Minimal Steps

1. Installation:

   composer require --dev api-platform/postman-collection-generator
   

   Add the bundle to AppKernel.php (or bundles.php for Symfony Flex) under non-production environments.

2. Configuration: Add the following to config/packages/dev/postman_generator.yaml (Symfony 4+) or app/config_dev.yml (Symfony 3):

   postman_generator:
       name: "My API"
       baseUrl: "http://localhost:8000"
       authentication: oauth2  # Optional, if using OAuth2
   

3. First Use Case: Generate the Postman collection with:

   php bin/console postman:collection:build
   

   This creates a postman_collection.json file in your project root.

Implementation Patterns

Workflows

1. Daily API Testing:

   • Run the generator command after making API changes to ensure Postman collections stay up-to-date.
   • Use the --output flag to specify a custom output path:

     php bin/console postman:collection:build --output=./docs/postman/
     

2. Integration with CI/CD:

   • Add the command to your CI pipeline (e.g., GitHub Actions, GitLab CI) to auto-generate collections on API changes.
   • Example GitHub Actions step:

     - name: Generate Postman Collection
       run: php bin/console postman:collection:build
     

3. Customizing Requests:

   • Implement a Request Parser to modify requests dynamically. Example:

     // src/Service/CustomRequestParser.php
     namespace App\Service;
     
     use PostmanGeneratorBundle\RequestParser\RequestParserInterface;
     use PostmanGeneratorBundle\Model\Request as PostmanRequest;
     
     class CustomRequestParser implements RequestParserInterface
     {
         public function parse(PostmanRequest $request)
         {
             $request->setHeader('X-Custom-Header', 'value');
             return $request;
         }
     }
     

   • Tag the service in services.yaml:

     services:
         App\Service\CustomRequestParser:
             tags:
                 - { name: postman.request_parser, priority: 100 }
     

4. Authentication Handling:

   • For OAuth2, configure the authentication: oauth2 option and provide credentials interactively during generation.
   • Extend with custom authentication via Command Parsers:

     // src/Service/CustomCommandParser.php
     namespace App\Service;
     
     use PostmanGeneratorBundle\CommandParser\CommandParserInterface;
     use Symfony\Component\Console\Question\Question;
     
     class CustomCommandParser implements CommandParserInterface
     {
         public function parse()
         {
             return [
                 new Question('Enter API Key: ', null, Question::TEXT),
             ];
         }
     
         public function execute($answers)
         {
             putenv('API_KEY=' . $answers[0]);
         }
     }
     

   • Tag the service:

     services:
         App\Service\CustomCommandParser:
             tags:
                 - { name: postman.command_parser, priority: 100 }
     

Gotchas and Tips

Pitfalls

1. Deprecated for API Platform 2.0+:

   • This bundle is not maintained and is obsolete for API Platform 2.0+. Use Swagger/OpenAPI (api-platform/core) + Postman’s native import instead:

     composer require api-platform/core
     

   • Generate OpenAPI schema:

     php bin/console api:openapi:generate
     

   • Import into Postman via the OpenAPI URL or file.

2. Authentication Quirks:

   • OAuth2 prompts may fail silently if authentication: oauth2 is set but no credentials are provided. Ensure you handle interactive input gracefully in CI/CD.

3. Request Parser Order:

   • Request parsers run in priority order (higher priority = earlier execution). Override existing parsers cautiously to avoid breaking functionality.

4. Base URL Mismatches:

   • Ensure baseUrl in config matches your API’s actual endpoint. Relative paths in the collection will break if this is incorrect.

Debugging

• Verbose Output: Run the command with -v or -vv to debug parser execution:

  php bin/console postman:collection:build -vv
  

• Validate JSON: Use a tool like JSONLint to validate the generated postman_collection.json.

Extension Points

1. Customizing Collection Metadata: Override the PostmanGeneratorBundle\Generator\CollectionGenerator service to modify the root collection object (e.g., add schemas, variables).

2. Dynamic Base URL: Use a Command Parser to fetch the baseUrl dynamically (e.g., from environment variables or a config service).

3. Filtering Endpoints: Implement a Request Parser to exclude specific routes (e.g., admin endpoints) by checking $request->getUrl().

Tips

• Symfony Flex Compatibility: For Symfony 4/5, place config in config/packages/dev/postman_generator.yaml and ensure the bundle is only loaded in dev environments via when@dev.

• Postman Environment Variables: The bundle generates environment variables for OAuth2. Extend this for other auth methods by customizing the PostmanGeneratorBundle\Model\Environment class.

• CI/CD Automation: Cache the generated collection to avoid regenerating it unnecessarily:

  - name: Generate Postman Collection
    run: |
      if [ ! -f "postman_collection.json" ]; then
        php bin/console postman:collection:build
      fi