Documentation

Laravel Rest API provides first-class integration with Scramble to automatically generate your API documentation from your resources, fields, relations and validation rules — with zero manual configuration.

The legacy rest:documentation command is deprecated and will be removed in a future major version. We recommend migrating to the Scramble-based integration described below.

Scramble integration (recommended)

Installation

Install Scramble in your project:

composer require dedoc/scramble

Then register the Lomkit extension in your config/scramble.php:

return [
    // ...
    'extensions' => [
        \Lomkit\Rest\Scramble\LomkitLaravelRestApiOperationExtension::class,
    ],
];

That's it. Visit /docs/api to see your fully generated documentation.

What is auto-generated

The extension reads your resources at boot time and automatically documents:

• Fields — all fields exposed via fields(), with their inferred OpenAPI type
• Validation rules — rules from rules(), createRules() and updateRules() are reflected as field descriptions and types
• Relations — all relations from relations(), including their Lomkit type (BelongsTo, HasMany, BelongsToMany, etc.)
• Search body — filters, sorts, selects, includes, scopes, pagination
• Mutate body — attributes object with all fields, nested relations block with the correct structure (single object vs array) per relation type
• Destroy / Restore body — resources array of IDs

Customization

The Lomkit extension is a standard Scramble extension. Every option Scramble provides — authentication schemes, servers, route filtering, custom routes, UI customization — is available to you without any restriction.

For a complete reference, refer to the Scramble documentation.

Filtering routes by authentication

A common pattern is to hide auth-protected routes from unauthenticated users:

use Dedoc\Scramble\Scramble;
use Illuminate\Routing\Route;
use Lomkit\Rest\Http\Controllers\Controller as LomkitController;

Scramble::routes(function (Route $route) {
    $controller = $route->getController();

    if (!$controller instanceof LomkitController) {
        return false;
    }

    if (!auth()->check()) {
        $protected = ['auth', 'auth:sanctum', 'auth:api', 'auth:passport'];

        if (collect($route->gatherMiddleware())->intersect($protected)->isNotEmpty()) {
            return false;
        }
    }

    return true;
});

Legacy documentation (deprecated)

⚠️ The following approach is deprecated and will be removed in the next major release. Please migrate to the Scramble integration above.

Generating documentation

php artisan rest:documentation

The documentation is generated based on registered routes. It is stored in your public folder and should be committed to version control. Avoid running this command directly on production — generate locally during development instead.

By default the generated documentation is accessible at /api-documentation. To customize or disable this, update the rest.routing configuration.

Configure data

You can configure OpenAPI information, servers and security in config/rest.php:

'documentation' => [
    'info' => [
        'title'          => config('app.name'),
        'summary'        => 'This is my project\'s documentation',
        'description'    => 'Find out all about my project\'s API',
        'termsOfService' => null,
        'contact' => [
            'name'  => 'My Company',
            'email' => 'email@company.com',
            'url'   => 'https://company.com',
        ],
        'license' => [
            'url'        => null,
            'name'       => 'Apache 2.0',
            'identifier' => 'Apache-2.0',
        ],
        'version' => '1.0.0',
    ],
    'servers'  => [
        ['url' => '/', 'description' => 'The current server'],
    ],
    'security' => [],
],

Extend operations

If you need to customize a specific operation, override the corresponding method on your controller:

namespace App\Rest\Controllers;

use Lomkit\Rest\Documentation\Schemas\Operation;

class UsersController
{
    public function generateDocumentationDetailOperation(Operation $operation): Operation
    {
        return $operation->withTags(['my custom tag']);
    }
}

Available methods: generateDocumentationDetailOperation, generateDocumentationSearchOperation, generateDocumentationMutateOperation, generateDocumentationActionsOperation, generateDocumentationDestroyOperation, generateDocumentationRestoreOperation, generateDocumentationForceDeleteOperation.

Add your own routes

Generate a dedicated service provider:

php artisan rest:documentation-provider

Register it in bootstrap/providers.php:

return [
    App\Providers\RestDocumentationServiceProvider::class,
];

Then declare custom routes in its boot() method:

use Lomkit\Rest\Facades\Rest;
use Lomkit\Rest\Documentation\Schemas\OpenAPI;
use Lomkit\Rest\Documentation\Schemas\Operation;
use Lomkit\Rest\Documentation\Schemas\Path;

public function boot(): void
{
    Rest::withDocumentationCallback(function (OpenAPI $openAPI) {
        $openAPI->withPaths([
            'myPath' => (new Path)
                ->withDescription('my custom path')
                ->withGet(
                    (new Operation)
                        ->withTags(['Callable'])
                        ->withSummary('You should call this !')
                ),
        ]);

        return $openAPI;
    });
}

For all available schemas and methods, see the GitHub repository.