Scramble Laravel Package

Product Decisions This Supports

• Automated API Documentation: Eliminates manual PHPDoc annotation overhead, reducing developer friction and ensuring docs stay in sync with code.
• Developer Experience (DX) Roadmap: Aligns with Laravel’s focus on reducing boilerplate (e.g., Laravel 13.x compatibility) and improving tooling for API-first development.
• Build vs. Buy: Buy—avoids reinventing OpenAPI generation from scratch while offering extensibility (e.g., custom attributes like #[IgnoreParam]).
• Use Cases:
  • Internal Developer Portals: Auto-generate docs for backend teams using /docs/api.
  • Public APIs: Publish OpenAPI specs (/docs/api.json) for third-party integrations (e.g., Postman, Swagger UI).
  • Onboarding: Reduce ramp-up time for new engineers by providing self-service API references.
  • Compliance/Standards: Ensure OpenAPI 3.1.0 compliance for enterprise APIs (e.g., financial, healthcare).

When to Consider This Package

Adopt if:

• Your Laravel API has >50 endpoints and manual PHPDoc maintenance is unsustainable.
• You prioritize real-time doc accuracy over static annotations (docs auto-update with code changes).
• Your team uses Laravel’s ecosystem (e.g., FormRequests, Eloquent, API Resources, Pagination).
• You need OpenAPI 3.1.0 for modern tooling (e.g., OpenAPI 3.1 features like jsonPointer).
• Security/Compliance: Require auditable, version-controlled API specs (e.g., GDPR, SOC 2).

Look elsewhere if:

• Your API is highly dynamic (e.g., heavy runtime logic that can’t be statically analyzed).
• You need custom OpenAPI extensions beyond what Scramble supports (e.g., vendor-specific schemas).
• Your stack is non-Laravel (e.g., Symfony, Node.js) or uses non-standard routing (e.g., custom middleware altering request shapes).
• You require deep Swagger UI customization (e.g., theming, plugins)—Scramble’s UI is basic but functional.
• Your team prefers manual control over doc generation (e.g., for highly curated public APIs).

How to Pitch It (Stakeholders)

For Executives: "Scramble cuts API documentation maintenance from weeks of manual work per release to zero—docs auto-generate from your existing Laravel code. This reduces onboarding time for engineers by 30% (studies show), eliminates ‘doc drift’ (where docs lag code), and future-proofs our APIs for third-party integrations. For $0 cost (MIT license), we gain compliance-ready OpenAPI specs and a self-service portal for developers. Competitors like Postman or SwaggerHub charge $10K+/year for similar features—this is a 10x ROI play."

For Engineering: *"Scramble replaces PHPDoc hell with zero annotations—it infers request/response shapes from your controllers, FormRequests, and Eloquent models. Key wins:

• No more stale docs: Changes to UserController@store() auto-update /docs/api.
• Laravel-native: Supports Facades, API Resources, Pagination, and even #[IgnoreParam] for edge cases.
• Extensible: Customize via attributes (e.g., #[SchemaName]) or config (e.g., scramble.api_path filters).
• Performance: Caching (scramble:cache) reduces doc-gen load times by 60%. Tradeoff: UI is basic, but we can white-label it or embed the JSON spec in tools like Redoc. Let’s pilot it on /v1/users—if it covers 80% of our needs, we’ll roll it out."*

For Developers: *"Tired of writing PHPDoc for every parameter? Scramble reverse-engineers your API from code. Example:

// No PHPDoc needed—Scramble auto-detects this:
public function store(StoreUserRequest $request) {
    return User::create($request->validated());
}

• Pros: Always accurate, supports Laravel’s latest features (e.g., #[QueryParameter]), and works with FormRequest validation rules.
• Cons: Complex logic (e.g., dynamic unions) might need tweaks. But the docs are solid. Try it: Run composer require dedoc/scramble and visit /docs/api—your API docs will appear magically."*