API Documentation with Scribe for Laravel

By Khimananda Oli | Last reviewed: August 2026

Outdated API references break integrations faster than bad code, especially when frontend teams or external partners rely on your endpoints being correct. API documentation with Scribe for Laravel solves this by extracting metadata directly from your routes, controllers, and validation rules to produce living docs that stay synchronized with your application. This guide walks you through configuring Scribe, annotating endpoints effectively, and automating generation so your documentation never drifts from production behavior.

How do you install and configure API documentation with Scribe for Laravel?

Start by requiring Scribe as a dev dependency. Since documentation generation should never ship to production containers, keeping it out of the main dependency tree reduces image size and attack surface.

composer require --dev knuckleswtf/scribe

Publish the configuration file to customize extraction strategies, output formats, and authentication defaults. This is where most teams get stuck — they accept defaults and later wonder why certain fields are missing or misclassified.

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

Edit config/scribe.php to match your project structure. The three settings that matter most in practice are routes (which route groups to document), strategies (how metadata is extracted), and type (output format). For a typical REST API built with Laravel Sanctum authentication, set the auth type to bearer and define a default token for example requests:

'auth' => [
    'enabled' => true,
    'default' => true,
    'in' => 'bearer',
    'name' => 'Authorization',
    'use_value' => env('SCRIBE_AUTH_TOKEN'),
],

Never hardcode tokens. Use environment variables even in development configurations. When documenting APIs that handle sensitive data — common in Nepal's growing fintech sector where data protection compliance matters — ensure your example responses never expose real PII. Scribe supports faker-based generation, but always audit generated examples before publishing.

How do you annotate Laravel controllers for accurate API documentation?

Scribe uses PHPDoc annotations and Laravel's native validation rules as its primary data sources. The annotation layer supplements what cannot be inferred from code alone: human-readable descriptions, grouped categories, and edge-case response examples.

Grouping and describing endpoints

Use @group at the class level to organize endpoints logically. Individual methods use @unauthenticated when an endpoint does not require auth despite global defaults, and @responseField to describe nested JSON structures that Scribe cannot infer from resource classes.

/
 * @group User Management
 * Endpoints for managing user accounts and profiles.
 */
class UserController extends Controller
{
    /
     * Update user profile.
     *
     * Validates and updates the authenticated user's profile information.
     * Returns the updated user resource.
     *
     * @responseField data object The updated user resource.
     * @responseField data.name string Full name of the user.
     * @responseField data.email string Primary email address.
     * @responseField meta.updated_at string ISO 8601 timestamp of last update.
     */
    public function update(UpdateProfileRequest $request): UserResource
    {
        // ...
    }
}

Leveraging Form Requests for automatic parameter docs

This is where Scribe shines compared to manual documentation tools. If you use dedicated Form Request classes, Scribe extracts field names, types, validation rules, and custom messages without any additional annotation. A well-structured request class serves double duty: runtime validation and documentation source of truth.

class UpdateProfileRequest extends FormRequest
{
    public function rules(): array
    {
        return [
            'name' => ['required', 'string', 'max:255'],
            'email' => ['required', 'email', Rule::unique('users')->ignore($this->user()->id)],
            'phone' => ['nullable', 'string', 'regex:/^9[0-9]{9}$/'],
        ];
    }

    public function messages(): array
    {
        return [
            'phone.regex' => 'Phone must be a valid Nepali mobile number.',
        ];
    }
}

Scribe converts these rules into parameter tables with types, required flags, and descriptions derived from message overrides. This eliminates the most common documentation failure mode: parameters documented in one place but validated differently in code.

How do you generate realistic response examples without exposing production data?

Scribe offers two complementary approaches: response calls (executing the endpoint against a test database) and manual/faker responses (defined via annotations or factory models). In practice, use both strategically rather than picking one exclusively.

Configuring safe response calls

Response calls execute actual HTTP requests during generation. This produces perfectly accurate examples but requires a disposable test environment. Configure the database, seeders, and authentication state in scribe.php:

'response_calls' => [
    'methods' => ['GET', 'POST', 'PUT', 'PATCH'],
    'config' => [
        'app.env' => 'testing',
        'database.default' => 'sqlite',
        'database.connections.sqlite.database' => ':memory:',
    ],
    'migrate_db' => true,
    'seed_db' => true,
    'seeder_class' => DatabaseSeeder::class,
],

A common mistake is running response calls against a shared staging database. This creates flaky docs when concurrent tests modify data. Always use an isolated SQLite in-memory database or a dedicated test schema. For teams following Laravel testing with Pest in CI/CD, align your Scribe test configuration with your existing test suite to avoid maintaining parallel environments.

Defining manual response examples

For endpoints with side effects, external dependencies, or non-deterministic outputs, define explicit examples using @response annotations or Eloquent model factories. This is safer and faster than response calls for most write operations.

/**
 * @response 201 scenario="User created successfully"
 * {"data":{"id":42,"name":"Anita Sharma","email":"[email protected]"},"meta":{"created_at":"2026-08-17T10:30:00Z"}}
 *
 * @response 422 scenario="Validation failed"
 * {"message":"The email has already been taken.","errors":{"email":["The email has already been taken."]}}
 */

Document error responses explicitly. Developers integrating your API need to know what 422, 403, and 404 payloads look like — not just the happy path. Scribe renders each scenario separately in the generated HTML, making error handling discoverable rather than buried in source code.

How does Scribe compare to OpenAPI and Swagger for Laravel APIs?

Choosing a documentation tool depends on your team's workflow, not feature checklists. Here is how the main options compare for Laravel projects in 2026:

Scribe occupies the practical middle ground: enough automation to reduce maintenance burden, enough control to handle complex APIs, and native Laravel integration that respects framework conventions. If your organization mandates OpenAPI as a design-first contract, use swagger-php. If you need fast internal docs with zero ceremony, try Scramble. For everything else — especially customer-facing APIs where accuracy matters — API documentation with Scribe for Laravel delivers the best balance.

How do you automate API documentation generation in CI/CD pipelines?

Documentation that requires manual regeneration becomes outdated within weeks. Automate generation as part of your deployment pipeline so every release ships with synchronized docs. This aligns with the principle that if documentation is not automated, observable, and audit-ready, it is not production-ready.

GitHub Actions example

Add a documentation job that runs after tests pass but before deployment. Cache the Scribe output to avoid regenerating unchanged endpoints:

docs:
  runs-on: ubuntu-latest
  needs: test
  steps:
    - uses: actions/checkout@v4
    - uses: shivammathur/setup-php@v2
      with:
        php-version: '8.4'
        extensions: mbstring, pdo_sqlite
    - run: composer install --no-interaction --prefer-dist
    - run: php artisan scribe:generate --force
    - uses: actions/upload-artifact@v4
      with:
        name: api-docs
        path: public/docs

The --force flag bypasses the interactive prompt. Store generated docs as artifacts or deploy them directly to your hosting target. For teams using GitLab CI for Laravel, adapt this pattern to GitLab's artifact and pages system.

Versioning and changelog tracking

Treat documentation as a versioned artifact. Tag doc releases alongside application versions. Scribe supports custom metadata injection — use this to embed build timestamps, git SHAs, or version numbers into generated output. When breaking changes occur, maintain parallel documentation versions rather than overwriting previous specs. External consumers need stable references even as your API evolves.

Make API Documentation with Scribe for Laravel Part of Your Release Process

Accurate API documentation with Scribe for Laravel is not a nice-to-have — it is infrastructure that prevents integration failures, reduces support load, and signals engineering maturity to partners and customers. Install Scribe, configure extraction strategies that match your codebase conventions, automate generation in your CI pipeline, and treat documentation quality as a deployment gate rather than an afterthought. If your team needs help establishing documentation workflows that survive real-world development velocity, reach out to discuss your API documentation strategy.