Oooas Laravel Package

Technical Evaluation

Architecture Fit

• Pros:

  • Enhanced Schema Flexibility: The new Schema::properties() method accepting SchemaContract instances improves type safety and reusability for complex nested schemas, aligning better with Laravel’s Eloquent relationships (e.g., hasMany, belongsTo).
  • CI/CD Stability: Fixed CI pipeline and updated dev dependencies reduce risk of integration failures in automated environments.
  • Consolidated Schema Management: Reduces boilerplate for defining properties (e.g., replacing manual property() calls with SchemaContract instances for consistency).
  • Laravel Synergy: Continues to leverage Laravel’s service container and annotations for minimal intrusion into existing codebases.

• Cons:

  • Backward Compatibility Risk: The change to Schema::properties() may require updates to existing custom schema definitions if they relied on the old method signature.
  • Limited Laravel-Specific Features: Still lacks native integration with Laravel’s auth systems (e.g., Sanctum/Passport) or resourceful controllers, requiring manual overrides.
  • Runtime Overhead: Spec generation remains runtime-dependent, which may impact performance in high-traffic or serverless environments.

Integration Feasibility

• Core Laravel Components:
  • Models: SchemaContract support simplifies mapping Eloquent models to OpenAPI schemas, especially for polymorphic or deeply nested relationships (e.g., morphTo or hasManyThrough).
  • Controllers: Annotations (e.g., @OA\Tag, @OA\Schema) can now leverage SchemaContract for cleaner property definitions, reducing redundancy.
  • Routes: Auto-discovery remains unchanged, but schema validation for route parameters/returns is now more robust with SchemaContract.
• Third-Party Packages:
  • Laravel Sanctum/Passport: Still requires custom decorators to integrate security schemes, but SchemaContract can standardize token/claim definitions.
  • API Resources: toArray()/toResponseArray() can now directly map to SchemaContract instances, improving response schema accuracy.

Technical Risk

• Schema Accuracy:
  • Risk: Mismatches between auto-generated specs and actual API behavior (e.g., missing error responses) may persist if SchemaContract definitions are incomplete.
  • Mitigation: Use CI/CD validation (e.g., openapi-linter) to compare specs against live API responses, with a focus on endpoints using SchemaContract.
• Backward Compatibility:
  • Risk: Existing code using Schema::properties() with non-SchemaContract arguments may break.
  • Mitigation: Audit custom schema definitions and update to use SchemaContract instances. Provide a migration script to automate this (e.g., regex search/replace in app/Models/).
• Performance:
  • Risk: Runtime spec generation could still impact cold starts in serverless environments.
  • Mitigation: Cache specs aggressively (e.g., Redis) and use php artisan ooas:generate in build pipelines for static exports.
• Dependency Stability:
  • Risk: Updated dev dependencies may introduce compatibility issues with newer Laravel/PHP versions.
  • Mitigation: Test against Laravel 10+ and PHP 8.2+ in a staging environment before full adoption.

Key Questions

1. How will SchemaContract adoption affect existing schemas?
   • Will a migration tool be created to automate updates to custom schema definitions?
   • How will partial adoption (mixing old and new Schema::properties() usage) be handled?
2. What’s the validation strategy for SchemaContract-based specs?
   • Will CI/CD include checks to ensure all schemas use SchemaContract instances?
   • How will discrepancies between SchemaContract definitions and live API responses be resolved?
3. How will auth/security schemes leverage SchemaContract?
   • Can SchemaContract standardize token payloads (e.g., Sanctum/Passport) or role-based access definitions?
   • Will decorators be provided to auto-generate security schemes from Laravel’s auth configuration?
4. What’s the impact on legacy APIs?
   • How will non-RESTful or manually documented endpoints be integrated with SchemaContract?
   • Will the package support hybrid modes (auto-generated + manual specs) during migration?
5. How will third-party package support evolve?
   • Are plans to add native adapters for Laravel Nova, Horizon, or Vite assets?
   • Can SchemaContract simplify integration with packages like spatie/laravel-api or fruitcake/laravel-cors?

Integration Approach

Stack Fit

• Laravel Core:
  • Service Provider: Register Ooas\OoasServiceProvider as before, but update to leverage SchemaContract for global schema definitions (e.g., config/ooas.php).
  • Route Prefix: Use middleware to scope spec generation (e.g., /api/docs) and exclude non-API routes.
  • Configuration: Extend config/ooas.php to include default SchemaContract instances for common models (e.g., User, Token).
• PHP Extensions:
  • PHP 8.2+: Fully utilize SchemaContract with attributes (e.g., [#[Schema]] for models).
  • Doctrine Annotations: Ensure compatibility with doctrine/annotations for hybrid annotation styles.
• Tooling:
  • Swagger UI/Redoc: Serve via Laravel’s public folder or use darkaonline/l5-swagger for enhanced UI.
  • OpenAPI Linter: Integrate stoplight/spectral in CI to validate SchemaContract-based specs.
  • Schema Registry: Use a shared SchemaContract library (e.g., app/Contracts/OpenAPI/Schema) for reusable definitions.

Migration Path

1. Assessment Phase:
   • Audit existing schema definitions for Schema::properties() usage and identify dependencies on non-SchemaContract arguments.
   • Map Eloquent models to SchemaContract instances (e.g., UserSchema::class).
2. Pilot Integration:
   • Start with a single module (e.g., /api/v1/auth) to test SchemaContract adoption.
   • Use SchemaContract for request/response models (e.g., CreateUserRequestSchema).
3. Incremental Rollout:
   • Phase 1: Replace manual Schema::properties() calls with SchemaContract instances for core models.
   • Phase 2: Update controllers/routes to use SchemaContract-based annotations (e.g., @OA\RequestBody(ref="#/components/schemas/UserSchema")).
   • Phase 3: Integrate auth schemes (e.g., Sanctum tokens) using SchemaContract and decorators.
4. Deprecation:
   • Phase out legacy Schema::properties() usage in favor of SchemaContract.
   • Use php artisan ooas:generate --strict to enforce SchemaContract compliance in CI.

Compatibility

• Laravel Versions:
  • Tested with Laravel 8/9/10 (PHP 7.4–8.2). For Laravel 11+, verify compatibility with Symfony 6+ components.
  • Workaround: Pin versions in composer.json if using older Laravel/PHP stacks.
• PHP Versions:
  • Requires PHP 7.4+ (for typed properties). For PHP 8.2+, leverage attributes (e.g., [#[Schema]]) for cleaner syntax.
• Dependencies:
  • Conflicts: Avoid other OpenAPI packages (e.g., zircote/swagger-php) to prevent duplicate specs.
  • Overrides: Use Ooas\Decorators\SpecDecorator to post-process specs (e.g., add missing security schemes).

Sequencing

1. Setup:
   • Install package: composer require goldspecdigital/oooas:^2.10.0.
   • Publish config: php artisan vendor:publish --provider="Ooas\OoasServiceProvider".
   • Update config/ooas.php to include default SchemaContract instances.
2. Schema Migration:
   • Create SchemaContract classes for critical models (e.g., app/Contracts/OpenAPI/UserSchema.php).
   • Example:

     namespace App\Contracts\OpenAPI;
     use Ooas\Contracts\SchemaContract;
     class UserSchema implements SchemaContract {
         public function properties(): array {
             return [
                 'id' => ['type' => 'integer'],
                 'name' => ['type' => 'string'],
                 'email' => ['type' => 'string', 'format' => 'email'],
             ];
         }
     }
     

3. Annotation Update:
   • Replace Schema::properties() calls with SchemaContract references in annotations:

     #[OA\RequestBody(ref="#/components/schemas/UserSchema")]
     public function store(StoreUserRequest $request) { ... }
     

4. Route Discovery:
   • Ensure routes are discoverable and exclude non-API routes via config/ooas.php.
5. Validation:
   • Add CI checks to validate SchemaContract usage and spec accuracy: