Laravel Scramble - API Documentation Generator

I needed to find a library to generate documentation for an existing Laravel API project I have so this was an opportunity to try out Laravel Scramble.

Setup

To add to your Laravel project, run this command to the project in the terminal.

composer require dedoc/scramble

Run the Laravel project.

php artisan serve

Then go to http://127.0.0.1:8000/docs/api to view the documentation, for me it was blank as I was using a new Laravel project.

To be able to edit the Scramble config file run the following to add it to your project.

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

Go to config/scramble.php to view the config settings for Scramble.

Config if not using /api route

For my project, the API project doesn’t use /api for my API routes so I had to make changes to make Scramble work.

Firstly I went to the app/config/scramble.php file and changed the api_path variable to a blank string as all API routes are located on the main domain.

<?php

use Dedoc\Scramble\Http\Middleware\RestrictedDocsAccess;

return [
    /*
     * Your API path. By default, all routes starting with this path will be added to the docs.
     * If you need to change this behavior, you can add your custom routes resolver using `Scramble::routes()`.
     */
    'api_path' => ''

Next, I had to update the app/Providers/AppServiceProvider.php to check all the routes and verify if the route is what should be added to the API documentation.

<?php

namespace App\Providers;

use Dedoc\Scramble\Scramble;
use Illuminate\Routing\Route;
use Illuminate\Support\ServiceProvider;

class AppServiceProvider extends ServiceProvider
{
    /**
     * Register any application services.
     */
    public function register(): void
    {
        //
    }

    /**
     * Bootstrap any application services.
     */
    public function boot(): void
    {
        Scramble::routes(function (Route $route) {
            $allowedRoutes = ['devsites', 'countries'];
            $isRouteValid = false;

            foreach ($allowedRoutes as $allowedRoute) {
                if (str_contains($route->uri, $allowedRoute)) {
                    $isRouteValid = true;
                    break;
                }
            }

            return $isRouteValid;
        });
    }
}

So for the routes to have the values in the $allowedRoutes variable then the $isRouteValid variable should be set to true. If the route doesn’t contain any of the values then $isRouteValid should be set to false.

Setting Permissions

By default, the API documentation is only accessible in the local environment. To make it available for production a Gate needs to be added to the app/Providers/AppServiceProvider.php file which references ‘viewApiDocs’.

<?php

namespace App\Providers;

use Illuminate\Support\Facades\Gate;
use Illuminate\Support\ServiceProvider;

class AppServiceProvider extends ServiceProvider
{
    /**
     * Register any application services.
     */
    public function register(): void
    {
        //
    }

    /**
     * Bootstrap any application services.
     */
    public function boot(): void
    {
        Gate::define('viewApiDocs', function () {
            return true;
        });
    }
}

API Documentation

Go to the route http://127.0.0.1:8000/docs/api to view the API documentation.

If routes are already setup with the /api route they show up automatically.

You can interact with the API by using the Send API Request button, some requests may require you to enter data into a text field such as POST and PUT requests.