Weave Code
Scramble Laravel Package
dedoc/scramble
Scramble generates up-to-date OpenAPI 3.1 API docs for Laravel automatically from your code—no PHPDoc annotations needed. Adds /docs/api UI and /docs/api.json schema routes (local by default, configurable via gate).
Automatic generation of API documentation for Laravel applications.
Frequently asked questions about Scramble
- How does Scramble generate OpenAPI docs without PHPDoc annotations?
- Scramble uses Laravel’s reflection capabilities to analyze your controllers, routes, and models at runtime. It infers parameters, responses, and validation rules automatically from your codebase, eliminating the need for manual PHPDoc annotations. For complex cases, you can use PHP attributes like #[IgnoreParam] or #[SchemaName] for granular control.
- Which Laravel versions does Scramble officially support?
- Scramble is actively maintained for Laravel 10, 11, 12, and 13. Older versions may require backports or forks, as the package aligns with Laravel’s latest features (e.g., API Resources in v13.19+). Always check the [release notes](https://github.com/dedoc/scramble/releases) for version-specific changes.
- Can Scramble handle Eloquent models, relationships, and paginated responses?
- Yes, Scramble natively supports Eloquent models, including relationships, eager loading, and paginated responses (e.g., `Paginator` or `LengthAwarePaginator`). It automatically documents model attributes, JSON:API payloads (since v13.19), and even nested resource structures without additional configuration.
- How do I customize or override auto-generated OpenAPI schemas?
- Use PHP attributes to fine-tune the output: #[IgnoreParam] hides parameters, #[SchemaName] renames fields, and #[Hidden] excludes endpoints. For broader changes, configure the `scramble.api_path` filter in `config/scramble.php` to exclude or modify routes globally. Complex cases may require extending Scramble’s inference logic via service providers.
- Is the `/docs/api` route secure in production? How can I restrict access?
- By default, `/docs/api` is only accessible in the `local` environment. To enable it in production, define the `viewApiDocs` gate in your `AuthServiceProvider`. For additional security, protect the route with middleware (e.g., API tokens) or configure environment-specific visibility via `scramble.environment` in the config.
- Will Scramble work with custom validation logic or DTOs?
- Scramble maps Laravel’s built-in validation (e.g., FormRequest rules) to OpenAPI schemas automatically. For custom validation logic or DTOs, use attributes like #[Schema] or extend the package’s `SchemaGenerator` to handle your specific cases. Dynamic validation (e.g., conditional rules) may require manual overrides via `#[IgnoreParam]` or custom attributes.
- How can I validate that the generated OpenAPI spec matches my live API?
- Integrate contract testing into your CI pipeline using tools like `spatie/laravel-api-tester` to assert that the OpenAPI spec matches actual API responses. Alternatively, use `openapi-cli` or `spectral` to lint the generated `api.json` file for schema compliance. This ensures docs stay accurate even as your API evolves.
- Does Scramble support API Resources (e.g., `toArray()`, `toResource()`)?
- Yes, Scramble supports Laravel’s API Resources since version 13.19+. It automatically infers the structure of `toArray()`, `toResource()`, and `toResourceCollection()` methods, including nested relationships and metadata. For custom resource logic, ensure your methods return consistent data shapes or use attributes to guide the generator.
- What if Scramble misinfers a route or parameter? How do I fix it?
- Use PHP attributes to correct misinferences: #[IgnoreParam] hides problematic parameters, #[SchemaName] renames fields, and #[Hidden] excludes entire endpoints. For complex cases, extend Scramble’s `RouteAnalyzer` or `ControllerAnalyzer` in a service provider. Always test changes by comparing the generated `api.json` with your live API responses.
- Can I use Scramble’s OpenAPI spec with tools like Postman or Redoc?
- Absolutely. The generated `api.json` is fully compliant with OpenAPI 3.1.0, so it works seamlessly with Postman (via import), Redoc (for custom branding), or API gateways like Kong/AWS API Gateway. To integrate with Redoc, serve the `api.json` and use Redoc’s standalone HTML template. For Postman, import the JSON file directly.
Weaver
How can I help you explore Laravel packages today?