Openapi Directory Laravel Package

Getting Started

Minimal Steps to First Use

1. Installation

   composer require apis-guru/openapi-directory
   

   (Note: This package is primarily a directory of OpenAPI specs, not a PHP library. The actual specs are fetched dynamically via HTTP.)

2. Fetching an API Spec

   use ApisGuru\OpenApiDirectory\Client;
   
   $client = new Client();
   $spec = $client->getSpec('swagger-petstore'); // Returns OpenAPI 3.x spec as array
   

3. First Use Case: Validate a Request

   $validator = new \ApisGuru\OpenApiDirectory\Validator($spec);
   $isValid = $validator->validateRequest('/pets', 'get', ['query' => ['limit' => 10]]);
   

Where to Look First

• API List – Browse available APIs (e.g., swagger-petstore, github, stripe).
• Client Class – Core class for fetching specs.
• Validator Class – For runtime request/response validation.

Implementation Patterns

1. Dynamic API Integration Workflow

// 1. Fetch spec once (cache it)
$spec = $client->getSpec('stripe');

// 2. Use in a Laravel middleware/service
public function handle(Request $request, Closure $next) {
    $validator = new Validator($spec);
    if (!$validator->validateRequest($request->path(), $request->method(), $request->all())) {
        abort(400, 'Invalid API request per Stripe spec');
    }
    return $next($request);
}

2. Generating API Documentation

// Convert spec to OpenAPI JSON for Swagger UI
$jsonSpec = json_encode($spec, JSON_PRETTY_PRINT);
file_put_contents(storage_path('app/swagger.json'), $jsonSpec);

3. Testing API Clients

// Mock API responses based on OpenAPI spec
$mockResponse = $validator->generateMockResponse('/pets', 'get');
$this->assertEquals(200, $mockResponse['status']);

4. Caching Strategies

// Cache specs for 1 hour (TTL)
$spec = Cache::remember("openapi_{$apiName}", now()->addHour(), function() use ($client, $apiName) {
    return $client->getSpec($apiName);
});

5. Laravel Service Provider Integration

// Register API validator as a singleton
public function register() {
    $this->app->singleton('openapi-validator', function ($app) {
        $spec = $app['apis.guru.client']->getSpec(config('services.api.name'));
        return new Validator($spec);
    });
}

Gotchas and Tips

Pitfalls

1. Rate Limiting

   • The apis.guru service may throttle requests. Cache specs aggressively.
   • Fix: Use Cache::forever() for static APIs (e.g., swagger-petstore).

2. Spec Version Mismatches

   • Some APIs return OpenAPI 2.0 (Swagger) vs. 3.x. Validate with:

     if (isset($spec['swagger'])) { // OpenAPI 2.0
         // Handle legacy spec
     }
     

3. Dynamic Path Parameters

   • OpenAPI specs may use {id} placeholders. Normalize paths before validation:

     $normalizedPath = str_replace('/{id}', '', $request->path());
     

4. Authentication Headers

   • The package does not handle auth (e.g., Authorization). Add middleware:

     if (!$validator->validateRequest($path, $method, $data) ||
         !$this->validateAuthHeaders($request)) {
         abort(401);
     }
     

Debugging Tips

• Inspect Raw Spec

  dd($client->getSpec('github')); // Debug full spec structure
  

• Validate Against a Known Good Spec Compare with Swagger Petstore.
• Check for Deprecated APIs Some specs (e.g., twitter) may be outdated. Verify with the API provider.

Extension Points

1. Custom Spec Fetching Override Client to fetch from a private registry:

   class PrivateApiClient extends Client {
       protected function fetchSpec($apiName) {
           return file_get_contents("https://your-registry.com/{$apiName}.json");
       }
   }
   

2. Schema Validation Extend Validator to add custom rules:

   $validator->addRule('/pets/{id}', 'post', function ($data) {
       return strlen($data['name']) > 3; // Custom rule
   });
   

3. Webhook Validation Use the validator for webhook payloads:

   $validator->validateResponse('/webhooks', 'post', $request->json()->all());
   

Config Quirks

• No Built-in Config File The package is lightweight; configure via code:

  $client = new Client([
      'cache_dir' => storage_path('openapi_cache'),
      'timeout' => 10,
  ]);
  

• Case-Sensitive Paths OpenAPI paths are case-sensitive. Normalize Laravel routes:

  $requestPath = strtolower($request->path());