Getting started

After you’ve installed Scramble, the first thing to do is to ensure that all the API routes are added to the docs.

Routes resolution

By default, all routes starting with api are added to the documentation. For example, yoursite.com/api/users will be added to the docs. This can be customized by modifying scramble.api_path config value. For example, if you want to add all routes starting with api/v1, you should set scramble.api_path to api/v1. Make sure you publish the config file first.

If your API routes use a different domain, you can account for it by modifying scramble.api_domain config value. By default, it is set to null which means that the current domain will be used. So if your API routes are on api.yoursite.com, you should set scramble.api_domain to api.yoursite.com.

Also, you may provide your own route resolver function using routes method of documentation’s configuration object in the boot method of a service provider. This way you can exclude routes or include just few ones. It will take precedence over the default route matching. For example, in your AppServiceProvider:

use Illuminate\Support\Str;
use Dedoc\Scramble\Scramble;
use Illuminate\Routing\Route;

public function boot(): void
{
    Scramble::configure()
        ->routes(function (Route $route) {
            return Str::startsWith($route->uri, 'api/');
        });
}

Route resolver function accepts a route and return bool determining if the route should be added to docs or not.

At this point your docs should be available at /docs/api URI.

Docs authorization

By default, you will only be able to access /docs/api route in the local environment.

Define viewApiDocs gate if you need to allow access in other environments.

To illustrate, if you want only the user with the email admin@app.com to access the docs in the production environment, you need to register the gate in one of your app’s service providers, such as App\Providers\AppServiceProvider:

use Illuminate\Support\Facades\Gate;

public function boot(): void
{
    Gate::define('viewApiDocs', function (User $user) {
        return in_array($user->email, ['admin@app.com']);
    });
}

API overview page

When you visit /docs/api first time, the page itself is almost empty.

You can add some content there by publishing the config file and setting scramble.info.description config value. Content can be as long as you want. Markdown is supported.

return [
    // ...
    'info' => [
        // ...
        'description' => 'This is my **API** description',
    ],
    // ...
];

Customizing API documentation’s URL

When installed, Scramble registers 2 routes by default:

1. /docs/api – The website for API documentation
2. /docs/api.json – The OpenAPI document in JSON format that describes the API

This can be customized by ignoring default routes using Scramble::ignoreDefaultRoutes, and then registering custom routes manually using the Scramble::registerUiRoute and Scramble::registerJsonSpecificationRoute methods.

You should call Scramble::ignoreDefaultRoutes from the register method of your application’s App\Providers\AppServiceProvider.

use Dedoc\Scramble\Scramble;

public function register(): void
{
    Scramble::ignoreDefaultRoutes();
}

And route registering methods can be called in routes/web.php. You can combine this with Laravel’s route registering features to get the routes you need. For example, here’s how you can register an API documentation website available on a subdomain:

use Illuminate\Support\Facades\Route;
use Dedoc\Scramble\Scramble;

Route::domain('docs.example.com')->group(function () {
    Scramble::registerUiRoute('api');
    Scramble::registerJsonSpecificationRoute('api.json');
});

Now the API documentation website will be available on docs.example.com/api and OpenAPI JSON document on docs.example.com/api.json.

Using expose configuration method

Documentation routes can be customized by explicitly providing the route’s paths using the expose method on documentation’s configuration object. It should be called in the boot method of a service provider.

public function boot(): void
{
    Scramble::configure()
        ->expose(
            ui: '/docs/v1/api',
            document: '/docs/v1/openapi.json',
        );
}

You can expose only the UI, or only the OpenAPI document by providing a single argument to expose method. For example, to expose only the OpenAPI document, provide the document argument:

public function boot(): void
{
    Scramble::configure()
        ->expose(document: '/docs/v1/openapi.json');
}

To disable default routes, simply pass false to expose method:

public function boot(): void
{
    Scramble::configure()
        ->expose(false);
}

If you need to register the documentation routes on a subdomain, you can pass closures to the ui and document parameters. The closure accepts the router instance and action that should be registered:

use Illuminate\Routing\Router;
use Illuminate\Support\ServiceProvider;

class AppServiceProvider extends ServiceProvider
{
    public function boot(): void
    {
        Scramble::configure()
            ->expose(
                ui: fn (Router $router, $action) => $router
                    ->domain('docs.example.com')
                    ->get('docs/v1/api', $action),
                document: fn (Router $router, $action) => $router
                    ->domain('docs.example.com')
                    ->get('docs/v1/openapi.json', $action),
            );
    }
}

Excluding (hiding) some routes from API documentation

If you need to exclude (hide) some routes from API documentation without re-defining routes resolution function, you can achieve that by adding attributes on route defining methods or controllers.

For excluding a method from documentation, you can add Dedoc\Scramble\Attributes\ExcludeRouteFromDocs attribute to the method. Or, if you need to exclude all controller’s methods, you can use Dedoc\Scramble\Attributes\ExcludeAllRoutesFromDocs.

For example, to hide a route defined in store method, simply add ExcludeRouteFromDocs to the method. In the following example, only index route will be added to the documentation.

<?php

namespace App\Http\Controllers\Api;

use App\Http\Controllers\Controller;
use Illuminate\Http\Request;
use Dedoc\Scramble\Attributes\ExcludeRouteFromDocs;

class JobController extends Controller
{
    public function index(Request $request)
    {
        /* ... */
    }

    #[ExcludeRouteFromDocs]
    public function store(Request $request)
    {
        /* ... */
    }
}