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. 
        });
}

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.

// routes/web.php
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).

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.