Scribe Laravel API Documentation: A Beginner’s Guide

So you’ve built an API in Laravel and now you need to document it. Don’t worry, Laravel has a package called Scribe that makes the process a breeze. In just a few commands, Scribe will generate beautiful API documentation from your Laravel routes and controllers.

You’ve already put in the work to build the API, so why spend hours manually documenting all your endpoints? With Scribe, you define your API using docblocks in your routes and controllers, and Scribe handles the rest. It will parse your code to generate a Postman collection, an OpenAPI (Swagger) specification, and a stylish frontend UI with all your API endpoints.

In this guide, you’ll learn how to get started with Scribe to generate API docs for your Laravel project. We’ll walk through installation, setup, writing docblocks, and customizing the frontend UI. By the end, you’ll have a full API documentation site up and running with almost no manual effort. Sound good? Let’s dive in!

What Is Laravel Scribe?

Laravel Scribe is a package that generates API documentation for your Laravel app. It analyzes your routes, controllers, and models to build a clean docs UI so you don’t have to manually write documentation.

Once installed, Scribe will generate an docs/index.html route in your app that serves the documentation. This includes:

• An overview of your API’s endpoints
• The request/response schema for each endpoint
• Examples of requests and responses
• Authentication requirements for endpoints
• Descriptions from your docblocks

Scribe supports many types of APIs, including REST, GraphQL, and OpenAPI. It has built-in support for popular Laravel tech like sanctum, jetstream, and laravel/ui.

To get started, install Scribe with Composer:

composer require --dev knuckleswtf/scribe

Then, publish its config file and assets:

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

Finally, add the @apiResource and @apiResourceCollection annotations to your controllers and run:

php artisan scribe:generate

This will build your documentation site in the docs/index.html route. How easy is that? With just a few commands, you’ve set up beautiful documentation for your API. Your users will thank you!

Scribe makes managing API docs a cinch so you can focus on building your app. Its powerful generation engine does the heavy lifting so you can keep things light and simple.

Getting Started With Laravel Scribe

To get started with Laravel Scribe, you’ll first need to install it. The easiest way is through Composer:

composer require --dev knuckleswtf/scribe

Once Scribe is installed, you’ll need to publish its config file:

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

This will publish a scribe.php config file to your config directory. In this file, you can configure which routes should be documented, which headers should be shown in the docs, etc.

Next, you’ll want to add the @api and @apiResource annotations to your API controllers. For example:

• @apiResource(“foos”)

The @apiResource annotation specifies the name that will be used in the documentation for this API resource. The @api annotations describe each API endpoint.

Once your controllers are annotated, you can generate the documentation using the scribe:generate Artisan command:

php artisan scribe:generate

This will generate an HTML documentation file at public/docs/index.html. You can now view your API docs at your-app-url/docs

Query and body parameters

To describe query or body parameters for your endpoint, use the @queryParam/@bodyParam tags (or #[QueryParam]/#[BodyParam] attributes) on the method handling it.

The @bodyParam tag takes the name of the parameter, a type, an optional “required” label, and an optional description. The @queryParam tag follows the same format, but the type is optional. If you don’t specify a type, Scribe will try to figure out the type based on the parameter name (or fallback to string).

/**
* @bodyParam user_id int required The id of the user. Example: 9
* @bodyParam room_id string The id of the room.
* @bodyParam forever boolean Whether to ban the user forever. Example: false
* @bodyParam another_one number This won't be added to the examples. No-example
*/
public function updateDetails()
{
}

/**
 * @queryParam sort string Field to sort by. Defaults to 'id'.
 * @queryParam fields required Comma-separated list of fields to include in the response. Example: title,published_at,is_public
 * @queryParam filters[published_at] Filter by date published.
 * @queryParam filters[is_public] integer Filter by whether a post is public or not. Example: 1
 */
public function listPosts()
{
    // ...
}

Scribe makes it a breeze to create beautiful documentation for your Laravel APIs. Between the annotations, config options, and built-in templates, you have everything you need to build great docs for your API consumers.

One of the most advantageous aspects of Scribe is that it has a course for creating user-friendly, maintainable and testable API documents. Isn’t it great? If you want to check it out, you can go to the course here.

Everything is that simple now you have an api document.

Would you like me to produce more content with Scribe? feel free to contact me here.