Keeps Dedoc Scramble OpenAPI 3.1 docs accurate for Laravel APIs—Form Requests for inputs, API Resources for responses, Sanctum middleware for auth, PHPDoc for summaries and edge-case responses, config/scramble.php, export and UI. Use when the user mentions Scramble, Dedoc, OpenAPI, Swagger, scramble:export, /docs/api, or API documentation generation for Laravel.
Scramble generates OpenAPI 3.1.0 from routes, Form Requests, API Resources, and controllers. Prefer code-first docs; annotations are optional enrichments.
Tune config/scramble.php:
| Setting | Role |
|---|---|
api_path | Document routes under this prefix (commonly api) |
info.version | Often from API_VERSION |
info.description | Docs homepage blurb |
ui.title, ui.theme, ui.hide_try_it | UI (Try It when not hidden) |
servers |
API base URLs; null may derive from api_path / api_domain |
$request->validate() on documented endpoints.required, string, integer, Rule::in, date, email, etc.).rules() (e.g. sometimes + page, per_page, filters).@bodyParam, @queryParam, @urlParam for human-readable descriptions.JsonResource::collection (or project wrappers like ApiResponse::json(Resource::make(...))) so Scramble reads toArray() shape.@return array<string, mixed> on toArray() when helpful.@response { ... } on controller methods when the payload is already shaped by an API Resource—Scramble infers from the Resource.@response (or other Scramble annotations) when not using a Resource and the schema must be described explicitly.auth:sanctum are documented as requiring authentication automatically.messages() still feed doc/error UX.@response blocks where Scramble supports them.@response / PHPDoc so the OpenAPI schema matches the real JSON (e.g. nested pagination)./docs/api—confirm route in your app).php artisan scramble:export for the spec (e.g. api.json).php artisan route:clear and php artisan config:cleartoArray() lists all fields; confirm Form Request rules cover all inputs; confirm return types are explicit.