Swagger Bundle Laravel Package

Getting Started

Minimal Setup

1. Installation

   composer require kleijnweb/swagger-bundle
   

   Add to config/bundles.php (Symfony) or config/app.php (Laravel via Symfony bridge):

   Kleijnweb\SwaggerBundle\KleijnwebSwaggerBundle::class => ['all' => true],
   

2. Configuration Place your OpenAPI/Swagger YAML file (e.g., swagger.yaml) in config/packages/swagger.yaml or define the path in config/packages/kleijnweb_swagger.yaml:

   kleijnweb_swagger:
       resource: '%kernel.project_dir%/config/packages/swagger.yaml'
   

3. First Use Case Define a route in your OpenAPI spec:

   paths:
       /api/users:
           get:
               summary: "Get all users"
               responses:
                   200:
                       description: "OK"
   

   Run:

   php bin/console swagger:generate
   

   This generates Symfony routes and validation rules from your OpenAPI spec.

Implementation Patterns

Workflow Integration

1. API-First Development

   • Write OpenAPI spec before implementing controllers.
   • Use swagger:generate to auto-generate route definitions in config/routes/swagger.yaml.
   • Manually implement controllers while adhering to the spec (e.g., request/response schemas).

2. Validation

   • Leverage Symfony’s validator component for request validation:

     # swagger.yaml
     parameters:
         - in: query
           name: limit
           schema:
               type: integer
               minimum: 1
     

     The bundle auto-generates validation constraints (e.g., @Assert\Min(1)).

3. Documentation-Driven Testing

   • Use the generated routes in PHPUnit tests:

     $client = static::createClient();
     $client->request('GET', '/api/users?limit=10'); // Matches OpenAPI spec
     

4. Partial Adoption

   • Mix auto-generated routes with manually defined ones.
   • Exclude specific paths from generation via swagger:generate flags:

     php bin/console swagger:generate --exclude=/admin/*
     

5. Schema Reuse

   • Define reusable schemas in components/schemas:

     components:
         schemas:
             User:
                 type: object
                 properties:
                     id: { type: integer }
                     name: { type: string }
     

   • Reference them in paths:

     responses:
         200:
             content:
                 application/json:
                     schema: { $ref: '#/components/schemas/User' }
     

Gotchas and Tips

Pitfalls

1. Outdated Package

   • Last release in 2017; may not support PHP 8.x or Symfony 5.6+ out-of-the-box.
   • Workaround: Fork the repo or patch manually (e.g., update SwaggerGenerator for newer Symfony components).

2. Route Name Conflicts

   • Auto-generated route names (e.g., swagger_get_api_users) may clash with manual routes.
   • Fix: Use swagger:generate --prefix=api/ to namespace routes or manually override in routes.yaml.

3. Validation Gaps

   • Complex nested validation (e.g., @Assert\Valid) may not generate correctly.
   • Tip: Manually add validation annotations in controllers for edge cases.

4. Circular References

   • OpenAPI specs with circular $ref schemas may cause generation errors.
   • Solution: Simplify schemas or use inline definitions temporarily.

5. Laravel-Specific Quirks

   • If using via Symfony bridge, ensure kernel.project_dir points to Laravel’s root.
   • Tip: Override KLEINJWEB_SWAGGER_RESOURCE in .env:

     KLEINJWEB_SWAGGER_RESOURCE=/path/to/swagger.yaml
     

Debugging Tips

1. Dry Run Use --dry-run to preview generated routes without writing to disk:

   php bin/console swagger:generate --dry-run
   

2. Log Generation Enable debug mode to log generation steps:

   # config/packages/kleijnweb_swagger.yaml
   kleijnweb_swagger:
       debug: true
   

3. Partial Generation Generate only specific sections (e.g., routes or validation):

   php bin/console swagger:generate --only=routes
   

Extension Points

1. Custom Generators Extend Kleijnweb\SwaggerBundle\Generator\SwaggerGenerator to add custom logic (e.g., API platform metadata).

2. Post-Generation Hooks Use Symfony’s event system to modify generated routes/validation:

   # config/packages/kleijnweb_swagger.yaml
   kleijnweb_swagger:
       events:
           post_generate: App\EventListener\SwaggerPostGenerateListener
   

3. Integration with API Platform Combine with api component to auto-generate CRUD operations from OpenAPI:

   # config/packages/api_platform.yaml
   api_platform:
       formats:
           jsonld:
               mime_types: ['application/ld+json']
           json:
               mime_types: ['application/json', 'application/vnd.api+json']