Multiple API versions

When you have multiple APIs or multiple API versions in your project, you can create different documentation websites using Scramble.

Registering an API

By default, Scramble automatically registers default API and uses configuration from config/scramble.php for the API.

To enable other API documentation websites, you need to register an API in boot method of a service provider using Scramble::registerApi method. As a first argument it accepts the API name, and a second parameter is configuration’s overrides (it is a part of configuration that will be merged with config from config/scramble.php).

use Dedoc\Scramble\Scramble;

public function boot(): void
{
    Scramble::registerApi('v1', [
        'api_path' => 'api/v1',
    ]);
}

You can also pass routes resolver function by chaining routes method and post-OpenAPI generation hook using afterOpenApiGenerated method.

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

public function boot(): void
{
    Scramble::registerApi('v2', ['info' => ['version' => '2.0']])
        ->routes(function (Route $route) {
            return Str::startsWith($route->uri, 'api/');
        })
        ->afterOpenApiGenerated(function (OpenApi $openApi) {
            // Some operations on the resulting documentation.
        });
}

Transformers are reused

When registering custom API, all transformers and server variables registered for the default API at that moment will be also used for registered custom API. This is done so can make a common configuration for all your APIs.

In this example, AddCustomAuth document transformer will be applied for both the default API and v2 API.

public function boot()
{
    Scramble::configure()
        ->withDocumentTransformers(AddCustomAuth::class);

    Scramble::register('v2', ['api_path' => 'api/v2']);
}

Registering routes

After you register an API, you need to register routes for the documentation. This is done by using the Scramble::registerUiRoute and Scramble::registerJsonSpecificationRoute methods. These methods accept route path as a first argument and API’s name as a second argument and return Route instance.

Scramble::registerUiRoute(path: 'docs/v2', api: 'v2');
Scramble::registerJsonSpecificationRoute(path: 'docs/v2.json', api: 'v2');

Scramble::registerUiRoute registers a route (UI route) for documentation website, and Scramble::registerJsonSpecificationRoute registers a route for documentation’s OpenAPI JSON document (API specification).

Using expose configuration method

To register the routes on which the documentation is available, you can use expose method:

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

public function boot(): void
{
    Scramble::registerApi('v2', ['info' => ['version' => '2.0']])
        ->expose(
            ui: '/docs/v2/api',
            document: '/docs/v2/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/v2/openapi.json');
}

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/v2/api', $action),
                document: fn (Router $router, $action) => $router
                    ->domain('docs.example.com')
                    ->get('docs/v2/openapi.json', $action),
            );
    }
}

Disabling default documentation routes

By default, Scramble registers docs/api as UI route, and docs/api.json as API specification route for default API (which is registered by default).

You can disable these routes by calling Scramble::ignoreDefaultRoutes from register method of a service provider. For example, in your App\Services\AppServiceProvider:

use Dedoc\Scramble\Scramble;

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

This is particularly useful when you need to have only those documentation websites you registered manually.

Using expose configuration method

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

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