Laravel Laravel Package

Getting Started

Install and publish config

composer require scalar/laravel
php artisan vendor:publish --tag=scalar-config

The package is a thin wrapper: it registers a route that serves the Scalar API Reference UI and points it at an OpenAPI document. Your first job is telling it where that document lives.

Open config/scalar.php and set the spec source. Depending on the version you install, this is typically a path or URL:

return [
    'spec' => env('SCALAR_SPEC', storage_path('api-docs/openapi.json')),
    'route' => env('SCALAR_ROUTE', 'docs/api'),
    // theme, middleware, etc. — read the published file, keys move between releases
];

Where to look first, in order

1. The published config/scalar.php — route prefix, spec location, middleware, theming keys.
2. php artisan route:list | grep -i scalar — confirms what URL the UI is actually mounted on.
3. The package's routes/ and src/ directories if the config is ambiguous; this package is small enough to read end-to-end in ten minutes and you will need to, because the README tends to lag the config.

First use case: docs for an existing API in under five minutes

Most Laravel teams do not hand-write OpenAPI. Pair this with a generator — Scramble is the path of least resistance:

composer require dedoc/scramble
php artisan vendor:publish --provider="Dedoc\Scramble\ScrambleServiceProvider"

Scramble exposes a JSON spec at /docs/api.json by default. Then either point Scalar at that URL:

'spec' => env('SCALAR_SPEC', '/docs/api.json'),

or, better, generate a static file at build time and point Scalar at the file. Visit /docs/api and you have an interactive reference with a "Try it" client wired to your real endpoints.

Implementation Patterns

Static spec file over live generation in production. Generating the spec on every request is fine locally and wasteful in production, and it also means your docs can 500 when a controller has a bad annotation. Export in CI and serve the artifact:

php artisan scramble:export --path=storage/app/api-docs/openapi.json

Then set SCALAR_SPEC to that path. Docs become immutable per deploy, which is exactly what you want when a consumer reports "the docs are wrong."

One reference per API surface. If you have a public API and an internal/admin API, don't merge specs. Mount two references behind two route prefixes and two config entries. If the package only supports a single route out of the box, register a second route in a service provider that returns the package's view with a different spec — this is the most common reason people fork or wrap the package.

// routes/web.php or a service provider
Route::get('/docs/internal', fn () => view('scalar::reference', [
    'spec' => '/api/internal.json',
]))->middleware(['auth', 'can:view-api-docs']);

Protect non-local environments. Public docs are a feature; public internal docs are an incident. Gate the route:

'middleware' => env('SCALAR_MIDDLEWARE')
    ? explode(',', env('SCALAR_MIDDLEWARE'))
    : ['web'],

Apply auth plus a policy or an IP allowlist. If the reference is fully client-side, remember the spec file also needs the same protection — gating the HTML while leaving openapi.json at a public URL protects nothing.

Wire it into your existing docs page. Scalar renders client-side, so it drops cleanly into a Blade layout as an island rather than owning the whole page. Keep your marketing/nav shell, mount the reference in a content div. If the package exposes a Blade component, use it; otherwise render the package view inside your layout with @include.

Versioned docs. For /v1 and /v2, keep the spec filenames versioned (openapi-v1.json, openapi-v2.json) and add a small version switcher that reloads the reference with a different spec URL. Do not try to express "which version am I looking at" through the config alone — consumers need to flip between them without editing URLs.

Theming and branding in config, not in a fork. Set the theme, dark mode, logo, and any proxyUrl or servers override in config. The "Try it" client needs to hit a reachable host — locally that may be http://localhost:8000, in staging a real domain. Set servers explicitly in the OpenAPI document rather than relying on relative resolution; it removes an entire class of "works in the browser preview, fails in the docs" bugs.

CI check. Add a step that exports the spec and validates it (npx @redocly/cli lint openapi.json or similar). A malformed spec produces a blank white page in Scalar with no server-side error, so catching it before deploy is materially cheaper than debugging it after.

Gotchas and Tips

A blank page is almost always an invalid or unreachable spec. The UI is client-side; a bad document fails silently in the browser. Open devtools, check the network tab for the spec request, and confirm the response is valid JSON/YAML with an openapi version key. Nine out of ten "Scalar is broken" reports are this.

Config caching bites on deploy. php artisan config:cache freezes the spec path and route. If you change SCALAR_SPEC via env on a running box, the old value persists until you re-cache. Standard Laravel, but people forget because docs feel like static assets.

Path resolution is the second-most-common failure. storage_path('...') and a bare 'openapi.json' are not the same thing. Be explicit: use absolute paths via helpers, or a URL with a leading slash. Relative paths tend to resolve against the package's own directory rather than the app root.

Browser caching of the spec. Scalar may cache the document. During active development, hard-reload or append a cache-buster. If you serve the spec from your own route, set Cache-Control: no-cache in local/staging and a short TTL with a hash/version query in production.

Route collisions. If you already have /docs from another package (L5-Swagger, Scribe, Scramble's own UI), one will shadow the other. Check route:list and set a distinct prefix like api-docs. Route registration order matters when a catch-all or fallback exists.

CORS and mixed content for remote specs. A spec hosted on another domain needs CORS headers, and a spec served over http inside an https page will be blocked. Prefer same-origin spec hosting.

"Try it out" hits the wrong base URL. The interactive client uses servers from the OpenAPI document, falling back to the page origin. Behind a load balancer or subdirectory, that's frequently wrong. Pin servers in the generated spec and, if the package supports it, use the proxy option to route requests server-side.

Content-Security-Policy and asset hosting. Scalar ships a client bundle. If your CSP is strict, allow its script/style sources — or self-host the assets if the package lets you publish them. Also decide CDN vs bundled: pinned, self-hosted assets are the right call for internal docs that must not depend on a third-party CDN at 3am.

Extension points, in order of preference. Config → published Blade view → wrapping route/view in your app → event/middleware hook → fork. The package is small; forking is cheap, but a fork means you own upgrades. Given a recent release cadence (last release listed as 2026-09-18), pin a version and read the changelog before bumping — the config surface is young and keys have moved.

Don't let the reference replace written guides. Scalar is excellent at endpoint-level truth and terrible at explaining why you'd call endpoints in sequence. Keep authentication walkthroughs, rate-limit policy, and multi-step tutorials in prose and deep-link into the reference. Teams that treat the generated UI as their whole documentation strategy end up with accurate endpoints and no onboarding story.