Swagger Resolver Bundle Laravel Package

Getting Started

Minimal Setup

1. Installation

   composer require adrenalinkin/swagger-resolver-bundle
   

   Add to config/app.php under providers:

   Adrenalinkin\SwaggerResolverBundle\SwaggerResolverBundle::class,
   

2. Publish Configuration

   php artisan vendor:publish --provider="Adrenalinkin\SwaggerResolverBundle\SwaggerResolverBundle" --tag="config"
   

   This generates config/swagger-resolver.php. Configure your Swagger JSON/YAML file path:

   'swagger' => [
       'path' => base_path('swagger.json'),
   ],
   

3. First Use Case: Validating Request Data Inject the resolver into a controller or service:

   use Adrenalinkin\SwaggerResolverBundle\SwaggerResolver;
   
   public function __construct(private SwaggerResolver $resolver) {}
   
   public function store(Request $request)
   {
       $data = $request->all();
       $this->resolver->validate($data, 'CreateUser'); // 'CreateUser' is the operation ID from Swagger
   }
   

Implementation Patterns

Core Workflows

1. Request Validation Use the resolver to validate incoming requests against Swagger schemas:

   $resolver->validate($request->json()->all(), 'UpdateProfile');
   

   • Operation ID: Must match the operationId in your Swagger spec (e.g., getUserById).
   • Schema Target: Supports parameters (query/path), requestBody, or responses validation.

2. Form Request Integration Extend Laravel’s FormRequest to auto-validate against Swagger:

   use Adrenalinkin\SwaggerResolverBundle\Traits\SwaggerValidatable;
   
   class StoreUserRequest extends FormRequest
   {
       use SwaggerValidatable;
   
       protected $operationId = 'CreateUser';
   }
   

   Override validateSwagger() to customize behavior.

3. API Response Validation Validate responses before sending:

   $responseData = ['id' => 1, 'name' => 'John'];
   $this->resolver->validate($responseData, 'getUser', 'responses');
   

Integration Tips

• Caching: Enable Swagger cache in config to avoid re-parsing on every request:

  'cache' => [
      'enabled' => true,
      'ttl' => 3600, // 1 hour
  ],
  

• Custom Resolvers: Extend Adrenalinkin\SwaggerResolverBundle\Resolver\ResolverInterface for custom validation logic.
• Event Listeners: Listen to swagger.resolver.validated or swagger.resolver.failed events for post-validation actions.

Gotchas and Tips

Common Pitfalls

1. Operation ID Mismatch

   • Issue: validate() fails with "Operation not found".
   • Fix: Ensure the operationId in your Swagger spec matches exactly (case-sensitive).
   • Debug: Use php artisan swagger:dump to inspect parsed operations.

2. Schema Path Errors

   • Issue: Validation fails for nested objects (e.g., address.city).
   • Fix: Use dot notation for nested paths in Swagger definitions:

     properties:
       address:
         type: object
         properties:
           city:
             type: string
     

3. Caching Quirks

   • Issue: Changes to Swagger file aren’t reflected.
   • Fix: Clear cache manually:

     php artisan cache:clear
     

   • Tip: Disable cache in development ('cache.enabled' => false).

4. Array Validation

   • Issue: Arrays with custom items fail validation.
   • Fix: Explicitly define items in Swagger:

     type: array
     items:
       type: string
       enum: [admin, user]
     

Debugging Tips

• Log Validation Errors: Enable debug mode in config:

  'debug' => true,
  

  Errors will log to storage/logs/laravel.log.

• Dump Swagger Structure: Use the Artisan command to inspect parsed operations:

  php artisan swagger:dump
  

Extension Points

1. Custom Validators Override the default resolver for specific schemas:

   $resolver->setCustomValidator('User', function ($data) {
       // Custom logic for 'User' schema
   });
   

2. Middleware Integration Create middleware to auto-validate all API requests:

   public function handle($request, Closure $next)
   {
       $operationId = $request->route()->getAction('operationId');
       $this->resolver->validate($request->all(), $operationId);
       return $next($request);
   }
   

3. Testing Mock the resolver in tests:

   $this->app->instance(SwaggerResolver::class, Mockery::mock(SwaggerResolver::class));