Ant Dedoc Scramble

Requests

• Use dedicated Form Request classes; avoid inline $request->validate() on documented endpoints.
• Use explicit rules so Scramble infers types (required, string, integer, Rule::in, date, email, etc.).
• Put query and body rules in the Form Request rules() (e.g. sometimes + page, per_page, filters).
• Optional: method PHPDoc with @bodyParam, @queryParam, @urlParam for human-readable descriptions.

Responses

• Return JsonResource / JsonResource::collection (or project wrappers like ApiResponse::json(Resource::make(...))) so Scramble reads toArray() shape.
• Add @return array<string, mixed> on toArray() when helpful.
• Do not add @response { ... } on controller methods when the payload is already shaped by an API Resource—Scramble infers from the Resource.
• Use @response (or other Scramble annotations) when not using a Resource and the schema must be described explicitly.

Authentication

• Routes behind auth:sanctum are documented as requiring authentication automatically.
• For custom auth, state requirements in controller PHPDoc (e.g. Bearer header).

Errors and custom envelopes

• Validation: messages in Form Request messages() still feed doc/error UX.
• Multiple shapes (e.g. errors vs success): use separate @response blocks where Scramble supports them.
• Custom pagination or non-resource top-level keys: document with @response / PHPDoc so the OpenAPI schema matches the real JSON (e.g. nested pagination).

Viewing and export

• UI (often /docs/api—confirm route in your app).
• php artisan scramble:export for the spec (e.g. api.json).

When docs look wrong

• php artisan route:clear and php artisan config:clear
• Confirm Resource toArray() lists all fields; confirm Form Request rules cover all inputs; confirm return types are explicit.

References

• Scramble docs
• OpenAPI 3.1
• Stoplight Elements (typical Scramble UI)