Openapi Runtime Laravel Package

Getting Started

Minimal Setup

1. Installation (if still needed for legacy projects):

   composer require jane/openapi-runtime
   

   Note: This package is deprecated; verify if your project absolutely requires it or migrate to janephp/janephp.

2. First Use Case:

   • Load an OpenAPI spec and generate a runtime client:

     use Jane\OpenApiRuntime\Client;
     
     $client = new Client('path/to/openapi.yaml');
     $response = $client->get('/path/to/endpoint');
     

3. Key Files:

   • Review src/Client.php for core functionality.
   • Check tests/ for usage examples (if available).

Implementation Patterns

Workflow Integration

1. API Client Initialization:

   // In a Laravel service provider (e.g., AppServiceProvider)
   public function register()
   {
       $this->app->singleton('openapi.client', function ($app) {
           return new \Jane\OpenApiRuntime\Client(config('openapi.spec_path'));
       });
   }
   

2. Request Handling:

   • Use dependency injection for requests:

     public function __construct(private Client $openApiClient) {}
     
     public function fetchData()
     {
         $response = $this->openApiClient->get('/users');
         return json_decode($response->getBody(), true);
     }
     

3. Middleware Integration:

   • Attach auth headers dynamically:

     $client->setDefaultOption('headers', [
         'Authorization' => 'Bearer ' . auth()->token(),
     ]);
     

4. Response Processing:

   • Normalize responses with Laravel helpers:

     $data = $response->getBody();
     return response()->json($data);
     

Gotchas and Tips

Pitfalls

1. Deprecation Warning:

   • This package is archived (last release: 2016). Prioritize migrating to janephp/janephp or alternatives like:
     • zircote/swagger-php
     • Laravel’s built-in HTTP client (Illuminate\Support\Facades\Http).

2. No Laravel-Specific Features:

   • Lacks native integration with Laravel’s service container, caching, or queue systems. Manual setup required.

3. Outdated PSR Standards:

   • May not comply with PSR-7/PSR-18 (e.g., no Psr\Http\Message interfaces). Use adapters if needed:

     use GuzzleHttp\Psr7\Utils;
     $body = Utils::streamFor($response->getBody());
     

Debugging Tips

1. Enable Verbose Logging:

   $client->setDefaultOption('debug', true);
   

   • Check logs for raw request/response details.

2. Validate OpenAPI Spec:

   • Use tools like Swagger Editor to pre-validate your spec before runtime.

3. Error Handling:

   • Wrap calls in try-catch:

     try {
         $response = $client->post('/endpoint', ['data' => $payload]);
     } catch (\Jane\OpenApiRuntime\Exception\RuntimeException $e) {
         Log::error('OpenAPI Error: ' . $e->getMessage());
         return response()->json(['error' => 'Service unavailable'], 503);
     }
     

Extension Points

1. Custom Middleware:

   • Extend Jane\OpenApiRuntime\Middleware\MiddlewareInterface to add logic (e.g., rate limiting):

     class LaravelAuthMiddleware implements MiddlewareInterface {
         public function __invoke($request, $next) {
             $request->setHeader('X-Laravel-Token', auth()->token());
             return $next($request);
         }
     }
     

2. Response Transformers:

   • Override response parsing in a subclass:

     class LaravelClient extends \Jane\OpenApiRuntime\Client {
         protected function parseResponse($response) {
             return json_decode($response->getBody(), true);
         }
     }
     

3. Caching:

   • Cache generated clients (if stateless):

     $client = Cache::remember('openapi.client', 86400, function() {
         return new Client(config('openapi.spec_path'));
     });