Laravel Scribe: Ultimate Guide to Auto-Generate API Documentation (Best Practices)

Laravel Scribe is one of the most powerful tools for automatically generating clean, interactive, and professional API documentation directly from your Laravel code. If you are building REST APIs and want accurate, always up-to-date documentation, Scribe is the best solution available.

What is Laravel Scribe

Laravel Scribe is a documentation generator that reads your routes, controllers, Form Requests, and PHPDoc comments to produce human-friendly API documentation. It eliminates manual documentation work and ensures your docs stay synchronized with your codebase.

Installing Laravel Scribe

Install Scribe as a development dependency using Composer.

composer require --dev knuckleswtf/scribe

After installation, publish the configuration file.

php artisan vendor:publish --tag=scribe-config

Generate documentation whenever your APIs change.

php artisan scribe:generate

Accessing Generated API Documentation

Once generated, your API documentation will be available at:

/docs/index.html

Grouping APIs Using @group

Grouping APIs improves readability and helps users navigate large documentation sets. You should group aggressively for better UX.

/**
 * Display list of orders
 *
 * @group Orders
 */

Authentication Configuration (Global)

Scribe supports global authentication configuration. This ensures all protected endpoints automatically show authentication requirements.

'auth' => [
    'enabled' => true,
    'default' => true,
    'in' => 'bearer',
    'name' => 'Authorization',
],

Authenticated and Unauthenticated Endpoints

You can explicitly define whether an endpoint requires authentication.

@authenticated
@unauthenticated

Documenting Request Body Parameters

Use @bodyParam to document JSON or form-data payloads.

@bodyParam email string required User email.

Documenting Query Parameters

Query parameters are commonly used for pagination and filtering.

@queryParam page int Page number. Example: 1

Documenting URL Parameters

URL parameters are essential for resource-based APIs.

@urlParam id int required Order ID.

Adding Custom Headers

You can explicitly document required headers for API requests.

@header Authorization string required Bearer token.

Defining API Responses

Example responses help consumers understand API output clearly.

@response 201 {
  "status": true,
  "message": "Order created"
}

Why Laravel Scribe is Best for API Documentation

Laravel Scribe offers automatic syncing, authentication awareness, clean UI, and developer-friendly annotations. It significantly improves API maintainability and developer onboarding.

Conclusion

If you are serious about building professional APIs, Laravel Scribe is not optional—it is essential. With proper annotations and grouping, you can generate production-ready documentation with minimal effort and maximum accuracy.