Scalar for Laravel

Use your OpenAPI documents to render modern API references in Laravel

Installation

Install the package via Composer:

composer require scalar/laravel

Then run the install command to publish the config file and finish setup:

php artisan scalar:install

That’s everything you need to get started. Prefer to publish things manually? You can:

# Publish the config file to config/scalar.php
php artisan vendor:publish --tag="scalar-config"

# Publish the Blade views (only needed if you want to customize them)
php artisan vendor:publish --tag="scalar-views"

Usage

You’ll need an OpenAPI (formerly Swagger) document to render your API reference. Several packages can generate one from your Laravel app:

• dedoc/scramble
• knuckleswtf/scribe
• vyuldashev/laravel-openapi

Point Scalar at your document in config/scalar.php. You can provide it in three ways:

A URL fetched by the browser — a path served by your own app, or an absolute URL:

'url' => '/openapi.yaml',
// 'url' => 'https://example.com/openapi.json',

A relative URL just needs to be reachable on the same origin. An absolute, cross-origin URL needs to be publicly accessible (and may go through the built-in proxyUrl).

A local file read on the server and embedded in the page — it never needs to be publicly accessible:

'file' => storage_path('app/openapi.json'),

Inline content — the raw OpenAPI document as a JSON or YAML string:

'content' => '{ "openapi": "3.1.0", "info": { "title": "My API", "version": "1.0.0" } }',

When more than one is set, file takes precedence over content, which takes precedence over url. Then visit /scalar to see your API reference.

Scalar client

The default CDN URL loads the latest Scalar client independently of Composer releases. Set cdn to choose a specific version or a self-hosted standalone bundle.

The Laravel theme, application title, proxy URL, and other published defaults stay unchanged. Review configuration.proxyUrl if requests should not use Scalar's public proxy.

Theme

The reference ships with a Laravel-flavored theme, enabled by default ('theme' => 'laravel' in the config). Scalar also comes with a range of built-in themes — see the configuration.theme option in config/scalar.php for the full list.

Multiple documents

Render more than one OpenAPI document behind a document switcher — useful for versioned APIs (v1, v2) or public vs. internal references. Define them in the sources config:

// config/scalar.php

'sources' => [
    ['title' => 'API v1', 'slug' => 'v1', 'url' => '/openapi/v1.yaml'],
    ['title' => 'API v2', 'slug' => 'v2', 'url' => '/openapi/v2.yaml', 'default' => true],
],

Each source accepts a title, an optional slug, one of url/content/file, and an optional default flag.

You can also register documents at runtime with the Scalar facade — for example in a service provider — which is handy when the list is dynamic:

use Scalar\Facades\Scalar;

Scalar::document('API v1')->url('/openapi/v1.yaml');
Scalar::document('API v2')->file(storage_path('app/openapi/v2.json'))->default();

Registered documents take precedence over the sources config. Document inputs belong in the top-level url, content, file, and sources settings. These keys are ignored inside configuration, so the rendered configuration contains only the selected document input.

Use configuration for other Scalar options. Configuration is serialized as JSON, so JavaScript callbacks cannot be supplied as PHP closures.

Under Laravel Octane the manager is a long-lived singleton, so register documents once (in a service provider). If you register per request, call Scalar::flush() first to avoid them stacking up.

Authorization

The Scalar API reference may be accessed via the /scalar route. By default, everyone will be able to access this route. However, within your App\Providers\AppServiceProvider.php file, you can overwrite the gate definition. This authorization gate controls access to Scalar in non-local environments. You are free to modify this gate as needed to restrict access to your documentation:

<?php

namespace App\Providers;

use App\Models\User;
use Illuminate\Support\Facades\Gate;
use Illuminate\Support\ServiceProvider;

class AppServiceProvider extends ServiceProvider
{
    public function boot(): void
    {
        Gate::define('viewScalar', function (?User $user) {
            return in_array($user?->email, [
                //
            ]);
        });
    }
}

The gate protects the reference page. A document fetched from a URL needs its own access rules. To keep a local document behind the page's gate, use file or content; authorized viewers receive the document in the HTML.

Testing

composer test

Changelog

Please see CHANGELOG for more information on what has changed recently.

Contributing

Contributions are welcome.

Credits

• Hans Pagel
• All Contributors

License

The MIT License (MIT). Please see License File for more information.