Scribe: Your Ultimate Companion for Laravel API Documentation

Scribe is a powerful tool that can save you countless hours of manual documentation work. By following this guide, you can easily set up Scribe in your Laravel project, configure it to match your needs, and generate beautiful, up-to-date API documentation with minimal effort.

https://demo.scribe.knuckles.wtf/

In the world of modern web development, APIs play a crucial role in facilitating communication between different systems and applications. As APIs grow in complexity, documenting them becomes increasingly important for developers to understand how to interact with them effectively. Laravel, one of the most popular PHP frameworks, offers a powerful tool called Scribe for generating comprehensive API documentation.

Scribe is an open-source package developed by the team at Knuckles.wtf. It leverages Laravel’s powerful routing and middleware system to generate beautiful and interactive documentation for your API. In this blog post, we’ll explore how to set up Scribe in your Laravel project, configure it to suit your needs, and generate documentation that will make your life easier.

Setting up Scribe in Your Laravel Project

Before we dive into the configuration details, let’s start by installing Scribe in your Laravel project. Open your terminal, navigate to your project’s root directory, and run the following command:

composer require --dev knuckleswtf/scribe

This command will install Scribe as a development dependency in your project. Once the installation is complete, you need to publish Scribe’s configuration file by running:

php artisan vendor:publish --provider="Knuckles\Scribe\ScribeServiceProvider"

This command will create a new file named scribe.php in your project's config directory. You can now customize the configuration according to your needs.

Configuring Scribe

Scribe offers a wide range of configuration options that allow you to tailor the generated documentation to your specific requirements. The configuration file we published earlier (config/scribe.php) is where you'll make most of these customizations.

Let’s take a look at some of the essential configuration options:

<?php

return [
    // The title of your documentation
    'title' => 'My API Documentation',

    // A short description of your API
    'description' => 'This is the documentation for my awesome API.',

    // The base URL for your API
    'base_url' => env('APP_URL'),

    // The routes to include in the documentation
    'routes' => [
        [
            'match' => [
                'prefixes' => ['api/*'],
                'domains' => ['*'],
            ],
            'exclude' => [
                'api/documentation',
            ],
        ],
    ],

    // ...
];

In this example, we’ve set the title, description, and base URL for our documentation. We’ve also configured Scribe to include all routes prefixed with api/* and exclude the api/documentation route.

You can find more configuration options in the config/scribe.php file, such as authentication settings, example languages, and options for generating Postman collections and OpenAPI specifications.

Generating Documentation

Once you’ve configured Scribe to your liking, you can generate the documentation by running the following command:

php artisan scribe:generate

This command will analyze your application’s routes, controllers, and request/response transformers to generate comprehensive documentation for your API. Depending on your project’s size and complexity, this process may take some time to complete.

If you’ve configured Scribe to generate a static HTML page ('type' => 'static'), the generated documentation will be saved in the public/docs directory by default. You can then access the documentation by visiting http://your-app-url/docs in your web browser.

Alternatively, if you’ve configured Scribe to generate a Blade view ('type' => 'laravel'), the documentation will be accessible via a route defined by Scribe. By default, this route is /docs, but you can change it in the configuration file.

Tips and Notes

• Documenting Your Routes: Scribe relies heavily on DocBlock comments and annotations to generate documentation. Make sure to document your routes, controllers, and request/response transformers using appropriate DocBlock comments and annotations for optimal results.
• Generating Example Responses: Scribe can generate example responses for your API endpoints based on your application’s models and transformers.
• Regenerating Documentation: As you make changes to your API, remember to regenerate the documentation by running php artisan scribe:generate again.