Weave Code
Scramble Laravel Package
dedoc/scramble
Scramble generates OpenAPI 3.1.0 documentation for your Laravel API automatically from your code, with no PHPDoc annotations required. Just install it to get a docs UI at /docs/api and a JSON spec at /docs/api.json, always kept up to date with your API.
Scramble is a Laravel package that automatically generates OpenAPI 3.1.0 API documentation from your existing codebase—no manual PHPDoc annotations required. By deriving docs directly from your routes, controllers, and models, it keeps documentation accurate and up to date as your code evolves.
Installing the package adds two routes: /docs/api for an interactive UI viewer and /docs/api.json for the raw OpenAPI JSON document. Routes are restricted to the local environment by default, with access configurable via a viewApiDocs gate.
- Zero-annotation generation straight from your Laravel code
- OpenAPI 3.1.0 output in JSON format
- Built-in UI viewer at
/docs/api - Gate-based authorization for documentation access
- Always up-to-date docs that never drift from your API
Frequently asked questions about Scramble
- How do I install Scramble in a Laravel application?
- Run composer require dedoc/scramble. The package ships as a Laravel service provider, so there is nothing else to register in a standard app. After install you get two routes: /docs/api, an interactive UI viewer, and /docs/api.json, the raw OpenAPI document. Both routes are only available in the local environment by default.
- Which Laravel and PHP versions does Scramble support?
- Scramble targets Laravel 10 through 13 on PHP 8.1 and above. Laravel 13 compatibility landed in v0.13.15, so pin a version at or above that if you are on a newer framework release. Distribution is Composer-only and MIT licensed, with no external services or migration steps required.
- Does Scramble require PHPDoc annotations or manual docblocks?
- No. Scramble generates the OpenAPI document through static analysis of your application source — routes, controllers, FormRequests, Eloquent models, and API resources — rather than from hand-written annotations. That is the core design goal: documentation stays in sync with the code because it is derived from the code. Attributes are available as optional escape hatches when inference gets something wrong.
- Are the /docs/api routes publicly accessible in production?
- Not by default. Scramble registers the documentation routes as local-only, so they are not exposed in production unless you change the behavior. Exposure is controlled by defining the viewApiDocs gate, which you should configure deliberately. Because default gating is environment-based only, a misconfiguration can publish an inventory of your internal endpoints, so review this before deploying.
- How do I fix an endpoint that Scramble documents incorrectly?
- Use the package's attributes and annotations to override inference: #[Endpoint], #[QueryParameter], #[SchemaName], #[IgnoreParam], and the @hidden and @deprecated annotations. Known weak spots are conditional fields using when(), union types, nullable handling, and dynamically built resource attributes, where inference can fall back to weaker schemas. In those cases the attributes become mandatory rather than optional.
- Does Scramble output OpenAPI 3.1.0, and will my tooling accept it?
- Yes, Scramble generates OpenAPI 3.1.0. Redoc and Scalar render it natively, but some code generation tools and certain gateway importers still assume 3.0.x. Verify the output against each downstream consumer, and if 3.1 is a blocker, plan a build-step conversion rather than downgrading the package.
- Is it safe to run Scramble in production or under Laravel Octane?
- Treat Scramble as a build-time or CI tool rather than a public runtime endpoint. v0.13.22 addressed a potential code execution issue under specific conditions in validation-rule expression evaluation, and v0.13.18 fixed a memory leak in long-running processes — both imply the package parses and evaluates application code. Generate the spec in CI and keep the docs routes gated.
- Does Scramble work with custom response envelopes, DTOs, or service-layer return types?
- It works best on conventional Laravel APIs: resource controllers returning models or JsonResource collections, validation in FormRequests, pagination via paginate or cursor, and Rule objects. Architectures that obscure inference — heavy repository or service abstractions returning mixed, custom response envelopes, non-Eloquent query builders, dynamically constructed DTOs — produce weaker schemas. In those codebases expect to lean heavily on attributes and manual overrides.
- How does Scramble compare to L5-Swagger or swagger-php for Laravel?
- L5-Swagger and swagger-php are annotation-driven: you write and maintain PHPDoc blocks, and the docs drift when the code changes. Scramble inverts that by deriving the spec from your code, which keeps it current but shifts control to inference and attributes. If you already have a hand-written spec, check for route path collisions and duplicated annotation coverage before migrating.
- Is Scramble stable enough for production, and should I pin the version?
- Scramble is pre-1.0 (v0.13.30), so minor releases can carry breaking changes in inference output and spec diffs between patch versions are expected — pin exact versions. Release history shows one dominant contributor, meaning high velocity but a low bus factor. Star count is popularity rather than verified production adoption, so run a spike against your own codebase. Also decide who reviews the generated spec diff in pull requests, and whether doc drift is a gated CI check.
Weaver
How can I help you explore Laravel packages today?