Scramble Laravel Package

Product Decisions This Supports

• Code-first vs. design-first API documentation. Scramble makes "the code is the spec" a viable strategy: it reads routes, controllers/closures, FormRequests, validation rules, Eloquent models, API Resources, and paginators to emit OpenAPI 3.1.0. That directly informs whether the team's roadmap includes public/partner APIs, where a trustworthy, always-current contract is a prerequisite.
• Build vs. buy for the docs/spec layer. It is a credible replacement for (a) hand-maintained YAML/PHPDoc annotations, (b) paid hosted doc portals at the early stage, and (c) custom internal tooling. It also reframes the buy decision: you may still buy a portal (ReadMe/Stoplight/Postman) later, but Scramble supplies the OpenAPI artifact those tools consume, so the decision is deferred and de-risked.
• Roadmap unlock: SDKs, sandboxes, contract tests, API review. An auto-generated /docs/api.json is the input for client SDK generation, Postman collections, mock servers, schema diffing/breaking-change detection in CI, and PR-level API review. These become cheap follow-on bets rather than new projects.
• Prioritization and capacity. Documentation drift is a recurring tax on every API change. Automating it converts ongoing maintenance effort into a one-time setup cost, freeing engineering capacity for feature work — a concrete input to quarterly planning.
• Scope decisions on API surface. Because undocumented/awkward endpoints surface visibly in the generated spec, the output doubles as an audit of API consistency (naming, pagination, error shapes), useful when deciding what to standardize, deprecate (@deprecated support), or hide (@hidden).
• Use cases to green-light: internal service APIs, mobile/BFF backends, partner integrations, public API v1 launches, and any Laravel app where a machine-readable contract is needed for QA or client teams.

When to Consider This Package

Adopt when:

• The stack is Laravel (roughly 10–13; Laravel 13 compatibility has landed) and the team uses idiomatic patterns — route model binding, FormRequests/validate(), API Resources, Eloquent, standard pagination. Inference quality is proportional to how conventional the code is.
• OpenAPI 3.1 is acceptable to downstream consumers (some older gateways/SDK generators still expect 3.0).
• The organization is comfortable with code as the source of truth, and reviewers will treat spec changes as part of code review.
• You want documentation available in days, not quarters, and can accept the occasional manual override via attributes (#[Endpoint], #[QueryParameter], response/header attributes) for the non-inferable 10–20%.
• You need a CI-exportable spec for contract tests or client generation, and you can gate /docs/api behind the viewApiDocs gate outside local.

Look elsewhere or add guardrails when:

• The backend is not Laravel (Symfony, Node, multi-language fleets) — inference is Laravel-specific.
• The org mandates design-first governance, where the hand-authored spec is the reviewed artifact and code must conform to it; Scramble inverts that relationship.
• APIs rely on heavy custom serialization, dynamic/array-shaped payloads, or non-standard response envelopes; you'll spend the savings on overrides.
• You need multi-service API cataloging, hosted portals, auth, analytics, or monetization — Scramble is a generator, not a platform (pair it with a portal).
• Version risk: the project is still 0.x (recent 0.13.x releases explicitly warn that generated output can change in ways equivalent to breaking changes for spec consumers). Pin the version, snapshot the spec, and diff it in CI.
• Sustainability risk: effectively single-maintainer, MIT, with a very small dependent footprint in library terms (expected for a dev-only dependency). Budget for the possibility of forking or replacing the inference layer if maintenance lapses.
• Correctness risk: inference is best-effort. If the spec drives revenue-bearing integrations, validate generated schemas against real responses and add a review step.

How to Pitch It (Stakeholders)

For executives (one paragraph): Scramble is a free, MIT-licensed Laravel package that produces an always-current OpenAPI 3.1 specification directly from our application code — no annotation work, no separate doc repo, no license cost. The business case is straightforward: API documentation that cannot silently drift, faster onboarding for partners and client teams, and a machine-readable contract that unlocks SDKs, contract tests, and API review at near-zero marginal cost. Setup is a composer require and an afternoon, so the downside is small and reversible; the upside is removing a recurring engineering tax and de-risking any public-API roadmap item.

For engineering: composer require dedoc/scramble adds /docs/api (Stoplight Elements UI) and /docs/api.json, local-only by default and controllable via the viewApiDocs gate. It infers request parameters from validation rules and FormRequests (including conditional rules, wildcards, enums, and regex), response shapes from Eloquent models, API Resources, collections and paginators, and works with closure routes as well as controllers. Where inference can't reach — custom headers, non-standard responses, operation IDs — use the provided attributes and annotations (#[Endpoint], #[QueryParameter], @deprecated, @hidden) rather than writing full specs. Put the generated JSON in CI: publish it as a build artifact, diff it to catch breaking changes, and feed it to client generators. Guidance: pin the minor version while on 0.x, review spec diffs like code diffs, and keep the docs route closed outside non-production environments until deliberately published.