Openapi Json Schema Bundle Laravel Package

Getting Started

Install the package via Composer:

composer require vendor/package-name

The package now requires PHP 8.4+ (breaking change). Verify your environment meets this requirement before proceeding.

For quick setup, register the service provider in config/app.php:

'providers' => [
    // ...
    Vendor\PackageName\PackageServiceProvider::class,
],

First Use Case: Resolve operation input schemas with the new OperationInputSchemaResolver:

use Vendor\PackageName\OperationInputSchemaResolver;

$resolver = new OperationInputSchemaResolver();
$schema = $resolver->resolve('operationName');

Implementation Patterns

Schema Resolution

Use the OperationInputSchemaResolver to dynamically fetch input schemas for API operations:

// Resolve schema for a specific operation
$schema = app(OperationInputSchemaResolver::class)->resolve('user.create');

// Integrate with Laravel's validation pipeline
$validator = Validator::make($request->all(), $schema->toArray());

JSON Schema Integration

Leverage the included JSON Schema unit tests as a reference for validating your own schemas:

use Vendor\PackageName\Tests\JsonSchemaTestCase;

class MySchemaTest extends JsonSchemaTestCase {
    public function testMySchema() {
        $this->assertValidSchema([
            'type' => 'object',
            'properties' => ['name' => ['type' => 'string']]
        ]);
    }
}

Workflow with API Controllers

use Vendor\PackageName\OperationInputSchemaResolver;

class UserController extends Controller {
    public function __construct(
        private OperationInputSchemaResolver $resolver
    ) {}

    public function store(Request $request, string $operationName) {
        $schema = $this->resolver->resolve($operationName);
        $request->validate($schema->toArray());

        // Proceed with business logic
    }
}

Gotchas and Tips

Breaking Changes

• PHP 8.4+ Required: Update your project or use a compatible version (e.g., ^0.1.0).
• Check for Deprecated Methods: Review the changelog for any removed functionality.

Debugging Tips

• Schema Resolution Errors: Use try-catch blocks to handle missing operations:

  try {
      $schema = $resolver->resolve('nonexistent.operation');
  } catch (\InvalidArgumentException $e) {
      Log::error("Schema resolution failed: " . $e->getMessage());
  }
  

Extension Points

• Custom Schema Resolvers: Implement Vendor\PackageName\Contracts\SchemaResolver for custom logic:

  class CustomResolver implements SchemaResolver {
      public function resolve(string $operationName): Schema {
          // Custom resolution logic
      }
  }
  

• Schema Validation: Extend JsonSchemaTestCase for reusable test cases:

  class ExtendedSchemaTest extends JsonSchemaTestCase {
      protected function setUp(): void {
          parent::setUp();
          $this->addCustomRule('customRule', fn($value) => !empty($value));
      }
  }
  

Configuration Quirks

• Service Binding: Ensure the resolver is bound in AppServiceProvider if not auto-discovered:

  public function register(): void {
      $this->app->bind(OperationInputSchemaResolver::class, fn($app) => new OperationInputSchemaResolver());
  }