How to document multiple APIs in Laravel with Scramble

A single Laravel application can contain multiple APIs. This is useful for:

• Different API versions
• Public and internal APIs
• APIs for frontend and backend consumption

With Scramble, you can create separate documentation for each API.

By default, Scramble registers an API called "default" and includes all endpoints where the URI starts with api/.

To include additional APIs, you simply register them, configure them, and expose their documentation.

#Example: documenting multiple API versions

Consider an application with two API versions:

// routes/api.php
Route::prefix('v1')->group(function () {
    // v1 routes
});
 
Route::prefix('v2')->group(function () {
    // v2 routes
});

We’ll configure the default API documentation to document version 1 (v1) first by updating the config to use api/v1 as the path prefix:

// config/scramble.php
...
'api_path' => 'api/v1',
...

Version 2 (v2) must be registered explicitly. This is done by calling registerApi in a service provider's boot method and providing specific configuration overrides for v2. The first parameter is the API name (which can be any string), and the second parameter is the Scramble configuration overrides applied on top of the default configuration (config/scramble.php).

In this example, the registered API named v2 (this is just our choice; it could be internal, public, etc.) will use the default configuration except for api_path, which is explicitly set for v2:

// app/Providers/AppServiceProvider.php
public function boot()
{
    Scramble::registerApi('v2', ['api_path' => 'api/v2']);
}

We also need to register the documentation routes for v2. This is done by calling registerUiRoute and registerJsonSpecificationRoute, passing the desired documentation path as the first parameter and the API name (as used in registerApi) as the second parameter:

// routes/web.php
Scramble::registerUiRoute('docs/v2', api: 'v2');
Scramble::registerJsonSpecificationRoute('docs/v2/api.json', api: 'v2');

Now, we have documentation available for both APIs:

#v1 documentation:

• GET docs/api - UI for viewing v1 documentation
• GET docs/api.json - OpenAPI 3.1.0 document for v1

#v2 documentation:

• GET docs/v2 - UI for viewing v2 documentation
• GET docs/v2/api.json - OpenAPI 3.1.0 document for v2

#Controlling documentation access

If some API versions should be public while others remain private, you can explicitly configure middleware for their documentation routes. This is useful when handling both public and internal APIs.

By default, documentation routes are only available in non-production environments. This logic is enforced by the RestrictedDocsAccess middleware. If you want v1 to be public and v2 restricted to non-production environments, remove RestrictedDocsAccess from v1 and add it to v2.

#Making v1 public

Remove RestrictedDocsAccess from the default configuration:

// config/scramble.php
...
'middleware' => [
    'web',
-   RestrictedDocsAccess::class,
],
...

#Restricting v2

Explicitly enable RestrictedDocsAccess for v2:

// app/Providers/AppServiceProvider.php
use Dedoc\Scramble\Http\Middleware\RestrictedDocsAccess;
 
public function boot()
{
    Scramble::registerApi('v2', [
        'api_path' => 'api/v2',
+       'middleware' => [
+           'web',
+           RestrictedDocsAccess::class,
+       ],
    ]);
}

Now, v1 documentation will be publicly accessible in production, while v2 will be restricted to non-production environments.

#Customizing v1 documentation routes

You can also customize the default documentation routes (GET docs/api, GET docs/api.json). To do this, disable default route registration in the service provider's register method:

// app/Providers/AppServiceProvider.php
public function register()
{
    Scramble::disableDefaultRoutes();
}

Then, manually register routes for the default API:

// routes/api.php
Scramble::registerUiRoute('docs/v1', api: 'default');
Scramble::registerJsonSpecificationRoute('docs/v1/api.json', api: 'default');

#Conclusion

Using Scramble, you can document multiple APIs within a single Laravel application — whether for different versions, public vs. internal access, or distinct client needs. You have full control over routes, middleware, and other configurations for each API.

Give Scramble a try if you haven't already: https://scramble.dedoc.co