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.

Including and excluding by route prefixes

api_path configuration also accepts include and exclude patterns:

1
'api_path' => [
2
    'include' => 'api',
3
    'exclude' => ['api/internal', 'api/debug'],
4
],

Without *, a pattern matches complete path segments: api matches api and api/users, but not apiary/users. With *, Scramble uses Laravel’s Str::is matching, so api/v* matches versioned paths.

A single static include remains the API server base and is stripped from documented paths. For example, api produces a server ending in /api and a /users path. With multiple includes or a wildcard, Scramble uses the application root as the default server and keeps full paths such as /api/v1/users. Configure servers explicitly if you need another base URL.

Defining your own route resolver

For more control, provide a route resolver with the documentation configuration object’s routes method in a service provider’s boot method. This lets you exclude routes or include only a few. It takes precedence over the default route matching. For example, in your AppServiceProvider:

1
use Illuminate\Support\Str;
2
use Dedoc\Scramble\Scramble;
3
use Illuminate\Routing\Route;
4

5
public function boot(): void
6
{
7
    Scramble::configure()
8
        ->routes(function (Route $route) {
9
            return Str::startsWith($route->uri, 'api/');
10
        });
11
}

A route resolver accepts a route and returns a bool that determines whether the route is added to the docs.

Documenting routes from a subdomain

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.

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

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:

1
use Illuminate\Support\Facades\Gate;
2

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

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.

1
return [
2
    // ...
3
    'info' => [
4
        // ...
5
        'description' => 'This is my **API** description',
6
    ],
7
    // ...
8
];

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.

1
use Dedoc\Scramble\Scramble;
2

3
public function register(): void
4
{
5
    Scramble::ignoreDefaultRoutes();
6
}

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:

1
use Illuminate\Support\Facades\Route;
2
use Dedoc\Scramble\Scramble;
3

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

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.

1
public function boot(): void
2
{
3
    Scramble::configure()
4
        ->expose(
5
            ui: '/docs/v1/api',
6
            document: '/docs/v1/openapi.json',
7
        );
8
}

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:

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

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

1
public function boot(): void
2
{
3
    Scramble::configure()
4
        ->expose(false);
5
}

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:

1
use Illuminate\Routing\Router;
2
use Illuminate\Support\ServiceProvider;
3

4
class AppServiceProvider extends ServiceProvider
5
{
6
    public function boot(): void
7
    {
8
        Scramble::configure()
9
            ->expose(
10
                ui: fn (Router $router, $action) => $router
11
                    ->domain('docs.example.com')
12
                    ->get('docs/v1/api', $action),
13
                document: fn (Router $router, $action) => $router
14
                    ->domain('docs.example.com')
15
                    ->get('docs/v1/openapi.json', $action),
16
            );
17
    }
18
}

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.

1
<?php
2

3
namespace App\Http\Controllers\Api;
4

5
use App\Http\Controllers\Controller;
6
use Illuminate\Http\Request;
7
use Dedoc\Scramble\Attributes\ExcludeRouteFromDocs;
8

9
class JobController extends Controller
10
{
11
    public function index(Request $request)
12
    {
13
        /* ... */
14
    }
15

16
    #[ExcludeRouteFromDocs]
17
    public function store(Request $request)
18
    {
19
        /* ... */
20
    }
21
}