Open Api Laravel Package

Getting Started

Minimal Setup

1. Installation

   composer require draw/open-api
   

   Add to composer.json if not autoloaded:

   "autoload": {
       "psr-4": {
           "App\\": "app/",
           "Draw\\OpenApi\\": "vendor/draw/open-api/src/"
       }
   }
   

   Run composer dump-autoload.

2. First Use Case Load an existing OpenAPI 2.0 spec (YAML/JSON):

   use Draw\OpenApi\Loader;
   
   $loader = new Loader();
   $spec = $loader->loadFromFile(__DIR__.'/path/to/spec.yaml');
   // or
   $spec = $loader->loadFromString(file_get_contents('spec.yaml'));
   

3. Key Classes to Know

   • Loader: Parse YAML/JSON into PHP objects.
   • Spec: Root object representing the OpenAPI spec.
   • Operation: Represents a single API endpoint (e.g., GET /users).
   • Schema: Defines request/response models.

Implementation Patterns

1. Dynamic API Documentation Generation

• Workflow:
  1. Load an existing spec (Loader).
  2. Modify operations/schemas via the Spec object.
  3. Export back to YAML/JSON:

     $yaml = $loader->dumpToYaml($spec);
     file_put_contents('updated-spec.yaml', $yaml);
     

• Example: Auto-generate endpoints from Laravel routes:

  $spec = $loader->loadFromString('{}');
  foreach (Route::getRoutes()->getRoutes() as $route) {
      $operation = $spec->addOperation(
          $route->methods()[0],
          $route->uri(),
          ['summary' => 'Dynamic endpoint']
      );
  }
  

2. Schema Validation & Transformation

• Pattern: Validate incoming requests against OpenAPI schemas.

  use Draw\OpenApi\Schema;
  
  $schema = new Schema(['type' => 'object', 'properties' => ['name' => ['type' => 'string']]]);
  $data = ['name' => 'John'];
  $isValid = $schema->validate($data); // Returns boolean or validation errors
  

• Laravel Integration: Use middleware to validate requests:

  public function handle($request, Closure $next) {
      $schema = $this->app['openapi']->getSchema('UserCreate');
      if (!$schema->validate($request->all())) {
          abort(422, 'Invalid request data');
      }
      return $next($request);
  }
  

3. Code Generation from Spec

• Use Case: Generate Laravel models/controllers from OpenAPI schemas.

  $spec = $loader->loadFromFile('spec.yaml');
  foreach ($spec->getSchemas() as $name => $schema) {
      $modelClass = $this->generateModel($name, $schema);
      file_put_contents("app/Models/{$name}.php", $modelClass);
  }
  

4. Testing API Contracts

• Pattern: Compare live API responses against OpenAPI specs.

  $spec = $loader->loadFromFile('spec.yaml');
  $response = Http::get('https://api.example.com/users/1');
  $operation = $spec->getOperation('GET', '/users/{id}');
  $this->assertEquals(
      $operation->getResponses()['200']->getSchema(),
      $response->object()
  );
  

Gotchas and Tips

1. Version Limitations

• Pitfall: Only supports OpenAPI 2.0 (Swagger). Avoid mixing with OpenAPI 3.x specs.
• Tip: Use Loader::validate() to check spec version:

  if (!$loader->validate($spec)->isValid()) {
      throw new \RuntimeException('Invalid OpenAPI 2.0 spec');
  }
  

2. Schema References

• Gotcha: Circular $ref references may cause infinite loops.
• Fix: Use Schema::resolveReferences() to resolve them:

  $resolvedSchema = $schema->resolveReferences($spec->getDefinitions());
  

3. YAML Parsing Quirks

• Issue: YAML anchors/aliases (e.g., &anchor) are not supported.
• Workaround: Convert YAML to JSON first if using anchors:

  yaml2json spec.yaml > spec.json
  

4. Performance with Large Specs

• Tip: Cache loaded specs in Laravel:

  $spec = Cache::remember('openapi-spec', 60, function() {
      return $loader->loadFromFile('spec.yaml');
  });
  

5. Extending the Library

• Extension Points:
  • Custom Validators: Implement Draw\OpenApi\ValidatorInterface.
  • New Schema Types: Extend Draw\OpenApi\Schema or add to Loader.
  • Example:

    class CustomSchema extends Schema {
        public function validate($data) {
            // Custom logic
        }
    }
    

6. Debugging Tips

• Dump Spec Structure:

  print_r($spec->toArray()); // Convert to associative array
  

• Validate JSON/YAML: Use jsonlint.com or yamllint.com to pre-check files before loading.

7. Laravel Service Provider

• Tip: Bind the loader to the container for easy access:

  public function register() {
      $this->app->singleton(Loader::class, function() {
          return new Loader();
      });
  }
  

• Usage:

  $spec = app(Loader::class)->loadFromFile('spec.yaml');