Api Doc Dumper Bundle Laravel Package

Getting Started

Minimal Setup

1. Installation:

   composer require bigz/api-doc-dumper-bundle --dev
   

   Ensure the package is listed in config/bundles.php under the dev environment:

   return [
       // ...
       Bigz\ApiDocDumperBundle\BigzApiDocDumperBundle::class => ['dev' => true],
   ];
   

2. First Use Case: Run the dump command to generate an OpenAPI spec JSON file:

   bin/console dump:api-doc
   

   Outputs apidoc.json in your project root (customizable via --file argument).

3. Prerequisites:

   • Ensure NelmioApiDocBundle is installed (this bundle depends on it).
   • Verify your routes are annotated with @ApiResource or configured in NelmioApiDoc.

Implementation Patterns

Workflow Integration

1. CI/CD Pipeline:

   • Trigger dump:api-doc in your CI (e.g., GitHub Actions) to auto-generate docs on dev pushes.
   • Example GitHub Actions step:

     - name: Generate API Docs
       run: php bin/console dump:api-doc --file=public/api-docs.json
     

2. Custom Output Paths:

   • Store docs in public/ for web access:

     bin/console dump:api-doc --file=public/api-docs.json
     

   • Use environment variables for flexibility:

     bin/console dump:api-doc --file=${API_DOCS_PATH:-apidoc.json}
     

3. Symfony Flex Integration:

   • If using Symfony Flex, ensure nelmio/api-doc-bundle is installed first:

     composer require nelmio/api-doc-bundle --dev
     

4. Scheduled Dumps:

   • Use Symfony’s CronBundle or a custom command to regenerate docs nightly:

     # config/packages/cron.yaml
     cron:
         jobs:
             dump_api_docs:
                 command: 'app:console dump:api-doc'
                 schedule: '0 3 * * *'
     

5. Versioned Docs:

   • Append a version tag to filenames (e.g., apidoc-v1.json) and update in README.md:

     bin/console dump:api-doc --file=docs/api/v1/apidoc-v1.json
     

Gotchas and Tips

Pitfalls

1. Missing NelmioApiDoc:

   • Error: Command "dump:api-doc" not found.
   • Fix: Install nelmio/api-doc-bundle first:

     composer require nelmio/api-doc-bundle --dev
     

2. Empty Output:

   • Cause: No routes are annotated with @ApiResource or configured in NelmioApiDoc.
   • Debug: Run bin/console debug:router and check for missing annotations.

3. Outdated Dependencies:

   • The package was last updated in 2019. Test thoroughly with newer Symfony/Laravel versions (if applicable).
   • Workaround: Fork the repo and update dependencies (e.g., NelmioApiDocBundle).

4. File Permissions:

   • Error: Permission denied when writing to project root.
   • Fix: Run with elevated permissions or specify a writable directory:

     bin/console dump:api-doc --file=var/api-docs.json
     

Debugging Tips

1. Verbose Output:

   • Add -v flag to debug:

     bin/console dump:api-doc -v
     

2. Validate OpenAPI:

   • Use Swagger Editor to validate the generated apidoc.json.

3. Customize NelmioApiDoc:

   • Configure NelmioApiDoc in config/packages/nelmio_api_doc.yaml to filter routes:

     nelmio_api_doc:
         areas: # Use areas to restrict routes
             path_patterns:
                 - ^/api(?!/internal)
     

Extension Points

1. Post-Processing:

   • Use a script (e.g., PHP or Node.js) to transform the JSON before publishing:

     // Example: Minify JSON with Node.js
     const fs = require('fs');
     fs.readFile('apidoc.json', (err, data) => {
         fs.writeFile('apidoc.min.json', JSON.stringify(JSON.parse(data)), () => {});
     });
     

2. Custom Command:

   • Extend the command to add features (e.g., Git commit hooks):

     // src/Command/DumpApiDocWithGit.php
     namespace App\Command;
     use Symfony\Component\Console\Command\Command;
     use Symfony\Component\Console\Input\InputInterface;
     use Symfony\Component\Console\Output\OutputInterface;
     
     class DumpApiDocWithGit extends Command {
         protected function execute(InputInterface $input, OutputInterface $output) {
             $this->getApplication()->find('dump:api-doc')->run(
                 $input,
                 $output
             );
             // Add Git logic here (e.g., commit changes)
         }
     }
     

3. Dynamic File Naming:

   • Override the command to include a timestamp or Git hash:

     // config/services.yaml
     App\Command\CustomDumpApiDocCommand::tags: ['console.command']
     

     // src/Command/CustomDumpApiDocCommand.php
     namespace App\Command;
     use Bigz\ApiDocDumperBundle\Command\DumpApiDocCommand;
     use Symfony\Component\Console\Input\InputOption;
     
     class CustomDumpApiDocCommand extends DumpApiDocCommand {
         protected function configure() {
             $this->addOption('file', null, InputOption::VALUE_REQUIRED, 'Custom filename', sprintf('apidoc-%s.json', date('YmdHis')));
         }
     }
     

4. Integration with API Gateways:

   • Publish the JSON to an internal API gateway (e.g., Kong, Apigee) via HTTP:

     curl -X POST --data-binary @apidoc.json http://gateway/api-docs