Introduction

Scribe helps you generate API documentation for humans from your Laravel/Lumen/Dingo codebase. See a live example at demo.scribe.knuckles.wtf.

Features

• Useful output:
  • Pretty single-page HTML doc, with human-friendly text, code samples, and in-browser API tester ("Try It Out")
  • Generates Postman collection and OpenAPI spec
• Smarts. Scribe can:
  • extract request parameter details from FormRequests or validation rules
  • safely call API endpoints to get sample responses
  • generate sample responses from Eloquent API Resources or Transformers
• Customisable to different levels:
  • Customise the UI by adjusting text, ordering, examples, or change the UI itself
  • Add custom strategies to adjust how data is extracted
  • Statically define extra endpoints or information that isn't in your codebase

Quick links

Wondering where to start? Try one of these:

• the getting started guide
• What's new in v4

If you're coming from mpociot/laravel-apidoc-generator, first migrate to v3`, then to v4.

tip

Scribe helps you generate docs automatically, but if you really want to make friendly, maintainable and testable API docs, there's some more stuff you need to know. So I made a course for you.🤗

Installation

Requirements

PHP 8.0 and Laravel/Lumen 8 or higher are required.

First, add the package via Composer:

composer require --dev knuckleswtf/scribe

Then complete the installation:

Laravel

Publish the config file by running:

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

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

Lumen

1. Copy the config file from vendor/knuckleswtf/scribe/config/scribe.php to your project as config/scribe.php.

2. Add these lines to your bootstrap/app.php. They'll ensure that Scribe is loaded, but only in your dev environment:

   bootstrap/app.php

   if (class_exists(\Knuckles\Scribe\ScribeServiceProvider::class)) {
       $app->register(\Knuckles\Scribe\ScribeServiceProvider::class);
       $app->configure('scribe');
   }

3. Add these lines to your Console/Kernel.php to enable Artisan commands:

   Console/Kernel.php

   use Laravel\Lumen\Application;
   
   public function __construct(Application $app)
    {
        parent::__construct($app);
        if (class_exists(\Knuckles\Scribe\Commands\GenerateDocumentation::class)) {
            $this->commands[] = \Knuckles\Scribe\Commands\GenerateDocumentation::class;
        }
        if (class_exists(\Knuckles\Scribe\Commands\MakeStrategy::class)) {
            $this->commands[] = \Knuckles\Scribe\Commands\MakeStrategy::class;
        }
        if (class_exists(\Knuckles\Scribe\Commands\Upgrade::class)) {
            $this->commands[] = \Knuckles\Scribe\Commands\Upgrade::class;
        }
    }

---

Alright, you're ready to start documenting! Follow the Getting Started guide to see what you can do with Scribe.