Scribe helps you generate API documentation for humans from your Laravel/Lumen/Dingo codebase. You can see a live example here.

Features

• Pretty single-page HTML doc, with human-friendly text, code samples, and included in-browser API tester (“Try It Out”)
• Extracts body parameters details from FormRequests or validation rules
• Safely calls API endpoints to get sample responses
• Supports generating responses from Transformers or Eloquent API Resources
• Generates Postman collection and OpenAPI spec
• Easily customizable with custom views and included UI components
• • Easily extensible with custom strategies
• • Statically define extra endpoints that aren’t in your codebase-

Installation

First, you’ve to add the package via Composer:

composer require --dev knuckleswtf/scribe

Publish the config file by running:

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

This will create a scribe.php file in your config folder.

Getting Started

1. Pick a type

The type key tells Scribe the type of docs setup you want. There are two options:

• static: This generates a simple index.html file (plus CSS and JS assets) in your public/docs folder. The routing of this file does not pass through Laravel, so you can’t add auth or any middleware.
• laravel: Scribe will generate a Blade view served via your Laravel app, allowing you to add auth or any middleware to your docs.

2. Choose your routes

The second thing you’ll need to do is tell Scribe what routes you want to document (the routes key). By default, it looks similar to this:

    'routes' => [
        [
            'match' => [
                'domains' => ['*'],
                'prefixes' => ['api/*'],
                'versions' => ['v1'],
            ],
            'include' => [
                // 'users.index', 'healthcheck*'
            ],
            'exclude' => [
                // '/health', 'admin.*'
            ],
        ],
    ],

The important key here is the prefixes. Set it to a path matching your API routes. For instance, the default config ([“api/"]) will match any endpoints that start with <your-app-url>/api/. You can set it to ["”] to match all endpoints.

Do a test run

Now, let’s do a test run. Run the command to generate your docs.

php artisan scribe:generate

Visit your newly generated docs:

• If you’re using static type, find the docs/index.html file in your public/ folder and open it in your browser.
• If you’re using laravel type, start your app (php artisan serve), then visit /docs.

Add general information about your API

Here are some things you can customize with Scribe:

• The API URL is shown in your docs
• The introductory text
• Authentication information
• Languages for the example requests
• A logo to show in your docs.

Add information to your routes

Scribe tries to figure out information about your routes, but you can improve it by adding more information. Here’s some information you can enrich:

• Groups (you can group your endpoints by domain eg “User management”, “Order Information”)
• URL parameters
• Request Headers
• Body parameters
• Query parameters
• Example responses
• Fields in the response

Generate and publish

After making changes as needed, you can run php artisan scribe:generate as many times as you want.

You’re good to go when you’re happy with how your documentation looks. You can add the generated documentation to your version control and deploy it as normal, and your users will be able to access it as you’ve configured it.

Need advanced customization?

Don’t like how the template looks? Want to change how things are organized, or add a custom language for the examples? Thinking of custom ways to extract more information about your routes? Check out the complete documentation for customization options.

Closing Note:

We are highly results-driven experts having experience in the grounds of Laravel web application development, CRM software, SAAS applications, and eCommerce web apps. So If you want to develop a custom web app you can contact us or Start a project with us.