A Practical Guide to API Documentation in Laravel with Scribe

Table of Contents

1. Introduction
2. What is Laravel Scribe?
3. Installation
4. Configuration
5. Generating Documentation
6. Customizing Documentation
7. Conclusion

---

Introduction

Imagine you’ve just finished developing a REST API for a project. The next step? Documenting your endpoints. Manual documentation can be tedious, error-prone, and time-consuming. Enter Scribe—an amazing Laravel package that generates API documentation automatically.

What this post covers:

1. Why Scribe is useful.
2. How to install, configure, and use it.
3. Practical examples of real-world usage.

---

What is Laravel Scribe?

Laravel Scribe is a package that automatically generates API documentation from your Laravel routes. It extracts information from your controllers, form requests, and other components to create detailed documentation. This documentation includes endpoints, request parameters, response examples, and more.

---

Installation

To get started with Laravel Scribe, you need to install it via Composer. Run the following command in your terminal:

composer require --dev knuckleswtf/scribe

After installing the package, you can publish the configuration file using:

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

This will create a scribe.php configuration file in your config directory.

---

Configuration

The scribe.php configuration file allows you to customize various aspects of your API documentation. Some key configurations include:

• title: The title of your API documentation.
• description: A brief description of your API.
• base_url: The base URL for your API.
• routes: Define which routes should be included in the documentation.

Here's an example configuration:

return [
    'title' => 'My API Documentation',
    'description' => 'This is the API documentation for My Application.',
    'base_url' => env('APP_URL'),
    'routes' => [
        [
            'match' => [
                'prefixes' => ['api/*'],
            ],
            'include' => [],
            'exclude' => [],
        ],
    ],
];

---

Generating Documentation

Once you've configured Laravel Scribe, you can generate the documentation by running:

php artisan scribe:generate

This command will create a set of static HTML files in the public/docs directory by default. You can access the documentation by navigating to http://your-app-url/docs.

---

Customizing Documentation

Laravel Scribe allows you to customize the documentation by adding annotations to your controllers and methods. Here are some common annotations:

• @group: Groups related endpoints together.
• @bodyParam: Describes a request body parameter.
• @response: Provides an example response.

Here's an example of a controller method with annotations:

/**
 * @group User Management
 *
 * Register a new user.
 *
 * @bodyParam name string required The name of the user. Example: Akram Ghaleb
 * @bodyParam email string required The email of the user. Example: [e-mail]
 * @bodyParam password string required The password of the user. Example: password123
 *
 * @response 200 {
 *     "message": "User registered successfully",
 *     "user": {
 *         "id": 1,
 *         "name": "Akram Ghaleb",
 *         "email": "[e-mail]"
 *     }
 * }
 */
public function register(Request $request)
{
    // Registration logic here
}

---

Conclusion

Laravel Scribe is an invaluable tool for generating API documentation in Laravel applications. It simplifies the process, ensures consistency, and provides a professional-looking documentation interface. By following the steps outlined in this blog post, you can easily integrate Laravel Scribe into your project and create comprehensive API documentation.

Happy coding 🚀