Scramble Laravel Package

Technical Evaluation

Architecture Fit

• Pros:

  • Zero-maintenance OpenAPI docs: Eliminates manual PHPDoc annotation overhead, aligning with modern Laravel practices (e.g., API-first development).
  • Deep Laravel integration: Supports core Laravel features (Eloquent, FormRequests, API Resources, Pagination, Auth) out-of-the-box, reducing customization needs.
  • OpenAPI 3.1.0 compliance: Future-proofs documentation for tooling (e.g., Swagger UI, Postman, Redoc).
  • Attribute-based customization: Uses modern PHP attributes (#[IgnoreParam], #[SchemaName]) for granular control without verbose annotations.
  • Performance optimizations: Caching support (v13.27+) and memory leak fixes (v13.18) mitigate runtime costs.

• Cons:

  • Inference limitations: Complex logic (e.g., dynamic method calls, nested closures) may require manual overrides or attributes.
  • Laravel version lock-in: Actively maintained for Laravel 10–13; older versions may need backports or forks.
  • UI dependency: Relies on a bundled Swagger UI; customization may require frontend work.

Integration Feasibility

• Low-risk for greenfield projects: Drop-in replacement for manual PHPDoc or tools like darkaonline/l5-swagger.
• Brownfield challenges:
  • Legacy PHPDoc: May conflict with existing annotations (resolvable via exclude config or attribute precedence).
  • Non-standard APIs: Custom middleware, filters, or macros may need explicit configuration (e.g., scramble.api_path filters).
  • Testing impact: Generated docs must be validated against real API responses (e.g., via contract testing).

Technical Risk

• High:
  • False positives/negatives: Inference errors (e.g., union types, dynamic properties) may produce inaccurate docs. Mitigate via:
    • Validation: Integrate with Laravel Pest/Tests to assert OpenAPI spec matches actual responses.
    • Fallbacks: Use #[IgnoreParam] or #[Hidden] for problematic endpoints.
  • Performance: Large codebases may hit memory limits during analysis (monitor via scramble:analyze logs).
• Medium:
  • Attribute conflicts: Custom attributes with similar names (e.g., #[Schema]) may require namespace qualification.
  • Auth/scopes: Complex auth logic (e.g., policy-based gates) may need manual securitySchemes configuration.

Key Questions

1. Coverage vs. Accuracy:

   • Should we prioritize full coverage (auto-generating all routes) or precision (manually curating critical endpoints)?
   • Tradeoff: Auto-generation reduces maintenance but may include deprecated/private routes.

2. CI/CD Integration:

   • How to enforce doc accuracy? Options:
     • Contract testing: Use spatie/laravel-api-tester to validate OpenAPI spec against live responses.
     • Schema validation: Add a CI job to lint the generated api.json (e.g., with spectral or openapi-cli).

3. Customization Depth:

   • Will we need to extend Scramble’s inference logic (e.g., for custom validation rules, DTOs, or GraphQL-like APIs)?
   • Example: If using spatie/laravel-query-builder, how to document dynamic filters?

4. Deployment Strategy:

   • Should /docs/api be:
     • Environment-restricted (default: local)?
     • Protected (e.g., behind API keys or auth)?
     • Cached (e.g., CDN or edge cache for api.json)?

5. Tooling Ecosystem:

   • Will we use Scramble’s UI exclusively, or integrate with:
     • Postman (via OpenAPI import)?
     • Redoc (for custom branding)?
     • API Gateway (e.g., Kong, AWS API Gateway for spec-driven routing)?

Integration Approach

Stack Fit

• Laravel Core: Native support for:

  • Routing: Auto-discovers all registered routes (including API groups).
  • Controllers: Infers parameters, responses, and exceptions.
  • Validation: Maps FormRequest rules to OpenAPI schemas (e.g., required, regex).
  • Eloquent: Documents models, relationships, and paginated responses.

• Extensions:

  • API Resources: Supports toResource(), toResourceCollection() (v13.19+).
  • JSON:API: Native support (v13.19+) for standardized payloads.
  • Testing: Works with Laravel’s HTTP tests to validate docs.

• Non-Laravel Components:

  • Custom middleware: May require manual securitySchemes or servers definitions.
  • GraphQL: Not supported; consider rebing/graphql-laravel + custom OpenAPI generation.

Migration Path

1. Pilot Phase:

   • Install in a non-production environment:

     composer require dedoc/scramble --dev
     

   • Test with a single module (e.g., /api/v1/users).
   • Validate:
     • Generated api.json matches expected structure.
     • UI renders correctly at /docs/api.
     • No false positives (e.g., admin-only routes).

2. Gradual Rollout:

   • Phase 1: Replace manual PHPDoc for new endpoints.
   • Phase 2: Migrate existing docs using:
     • scramble.api_path filters to exclude legacy routes.
     • Attributes (#[IgnoreParam]) for problematic endpoints.
   • Phase 3: Integrate into CI (e.g., fail build if api.json schema drifts).

3. Legacy Handling:

   • For projects with heavy PHPDoc usage:
     • Use scramble:analyze --dry-run to identify conflicts.
     • Gradually replace PHPDoc with attributes (e.g., #[SchemaName]).

Compatibility

Sequencing

1. Pre-requisites:

   • Laravel 10+ (recommended: 11–13).
   • PHP 8.1+ (PHP 8.5+ for deprecation fixes).
   • Composer dependencies resolved.

2. Installation:

   composer require dedoc/scramble
   php artisan scramble:install
   

   • Configure viewApiDocs gate in App\Providers\AuthServiceProvider if needed.

3. Configuration:

   • Basic: Edit config/scramble.php for:
     • api_path: Filter routes (e.g., ['prefix' => 'api/v1']).
     • cache: Enable true for performance.
   • Advanced: Publish config and extend via service provider:

     php artisan vendor:publish --provider="Dedoc\Scramble\ScrambleServiceProvider"
     

4. Validation:

   • Test /docs/api locally.
   • Compare api.json with a golden copy (e.g., using diff or CI checks).

5. CI Integration:

   • Add a script to validate docs:

     # .github/workflows/docs.yml
     - name: Validate API Docs
       run: |
         curl -s http://localhost/docs/api.json | jq . > generated.json
         git diff --exit-code -- docs/golden.json generated.json
     

Operational Impact

Maintenance

• Pros:

  • Reduced toil: No manual updates when API changes (e.g., adding a field to a request).
  • Single source of truth: Docs stay in sync with code.
  • Attribute-based: Customizations are localized (e.g., #[IgnoreParam] on a single method).

• Cons:

  • Debugging complexity: Inference errors may require deep code analysis.
  • Version pinning: Must update Scramble with Laravel major versions (e.g., v13.x for Laravel 13).
  • Configuration drift: Custom scramble.php settings may need updates across environments.