Laravel Automatic API Documentation

Keeping API documentation up-to-date can be a hassle, especially as your code changes. The Laravel Automatic API Documentation package, Scramble, simplifies this process by automatically generating API documentation. This means you don’t have to write PHPDoc annotations manually. Scramble uses static analysis and Laravel’s conventions to keep your docs current and accurate.

#Why Use Scramble?

Scramble’s main goal is to generate as much API documentation as possible automatically. This way, you can focus on writing code instead of worrying about annotating every parameter or field, which often leads to outdated documentation. With Scramble, your API docs are always in sync with your code, ensuring consistency.

#Key Features

• When you install Scramble in your Laravel API project, two new routes are added:

• /docs/api: This displays your API documentation.

• /docs/api.json: This provides an OpenAPI document in JSON format that describes your API.

Some cool features of Scramble include:

• Customizable Route Resolution: You can customize how routes are resolved using the Scramble::routes() method.
• Documentation Authorization: Control who can access your documentation.
• Server Configuration: Tailor your server settings to fit your needs.
• Security Schemes: Implement common security practices like JWT, Basic Auth, OAuth2, and more.
• Extensions API: Extend and customize how documentation is generated.

#Installation & Setup

To use Scramble, you’ll need:

• PHP 8.1 or higher
• Laravel 10.x or higher

Install Scramble via Composer:

composer require dedoc/scramble

Once installed, you’ll have two new routes in your application:

• /docs/api: The UI viewer for your documentation.
• /docs/api.json: The OpenAPI document in JSON format that describes your API.

That’s it! You can now visit /docs/api to see your API documentation. By default, these routes are only available in the local environment, but you can change this by defining a viewApiDocs gate.

#Publishing the Config

If you want, you can publish the package’s config file to customize it:

php artisan vendor:publish --provider="Dedoc\Scramble\ScrambleServiceProvider" --tag="scramble-config"

This allows you to change how API routes are resolved and tweak details of the OpenAPI document. The config file gives you control over the API path, domain, version, description, servers, middleware, and more.

#Getting Started

Once Scramble is installed, you’ll want to make sure all your API routes are included in the documentation.

#Routes Resolution

By default, Scramble adds all routes that start with api to the documentation.

For example, yoursite.com/api/users will be included.

You can customize this by changing the scramble.api_path config value. If you want to add routes starting with api/v1, set scramble.api_path to api/v1. Make sure to publish the config file first.

If your API routes use a different domain, you can adjust the scramble.api_domain config value. By default, it’s set to null, meaning the current domain will be used. So if your API routes are on api.yoursite.com, set scramble.api_domain to api.yoursite.com.

You can also create your own route resolver function using Scramble::routes in the boot method of a service provider. This lets you exclude routes or include only specific ones. For example, in your AppServiceProvider:

use Illuminate\Support\Str;
use Dedoc\Scramble\Scramble;
use Illuminate\Routing\Route;
 
public function boot(): void
{
    Scramble::routes(function (Route $route) {
        return Str::startsWith($route->uri, 'api/');
    });
}

The route resolver function takes a route and returns a true or false value, deciding whether the route should be added to the docs.

#Docs Authorization

By default, you can only access the /docs/api route in the local environment. If you need to allow access in other environments, you can define a viewApiDocs gate.

For example, if you want only the user with the email admin@app.com to access the docs in the production environment, 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']);
    });
}

#Customizing the API Documentation URL

By default, Scramble registers two routes:

• /docs/api: The API documentation website.
• /docs/api.json: The OpenAPI document in JSON format.

You can customize these routes by ignoring the defaults using Scramble::ignoreDefaultRoutes, and then registering custom routes manually using Scramble::registerUiRoute and Scramble::registerJsonSpecificationRoute.

Call Scramble::ignoreDefaultRoutes from the register method of your app’s App\Providers\AppServiceProvider:

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

Then, you can set up the routes in routes/web.php. For example, to make the API documentation 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, your API documentation will be available at docs.example.com/api and the OpenAPI JSON document at docs.example.com/api.json.