Getting Started

Minimal Setup

Installation:

composer require knuckleswtf/scribe

Publish the configuration:

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

First Run: Generate documentation by running:
```
php artisan scribe:generate
```
Access the generated HTML at storage/app/public/scribe/index.html (or your configured output path).
First Use Case:
- API Testing: Use the "Try It Out" panel in the generated HTML to test endpoints directly from the docs.
- Postman Import: Download the Postman collection from the UI to import into Postman for further testing.

Key Configuration

Base URL: Configure in config/scribe.php:
```
'base_url' => env('SCRIBE_URL', 'http://localhost:8000'),
```
Supports Blade syntax (e.g., {{ config('app.url') }}).
Output Path: Defaults to storage/app/public/scribe. Customize via:
```
'output_path' => storage_path('app/public/scribe'),
```

Initial Workflow

Generate Docs:
```
php artisan scribe:generate
```
- Automatically extracts routes, request/response schemas, and examples from your Laravel codebase.
View Docs:
- Serve the HTML via Laravel's built-in server:
```
php artisan serve
```
- Access at http://localhost:8000/scribe/index.html.
Iterate:
- Use the "Try It Out" panel to test endpoints interactively.
- Refine documentation by adding custom descriptions or examples (see Implementation Patterns).

Implementation Patterns

Core Workflows

1. Automated Documentation Generation

Route Extraction: Scribe automatically discovers all Laravel routes (web, API, and controller-based) and generates documentation for each endpoint.
- Example: A GET /api/users route will appear in the docs with:
  - Request parameters (query/path/body).
  - Response schemas (from Eloquent models, API Resources, or manual definitions).
  - Example responses (generated via factories or actual API calls).

Request/Response Handling:

Form Requests: Extract validation rules and map them to OpenAPI schemas.

// app/Http/Requests/StoreUserRequest.php
public function rules()
{
    return [
        'name' => 'required|string|max:255',
        'email' => 'required|email|unique:users',
    ];
}

Scribe converts these to OpenAPI required: true and type: string fields.

API Resources: Automatically infers response schemas from Illuminate\Http\Resources\Json\JsonResource:

// app/Http/Resources/UserResource.php
public function toArray($request)
{
    return [
        'id' => $this->id,
        'name' => $this->name,
        'email' => $this->email,
    ];
}

Manual Overrides: Use attributes to customize documentation:

use Knuckles\Scribe\Attributes\Group;
use Knuckles\Scribe\Attributes\Deprecated;

#[Group('Users')]
#[Deprecated('Use /api/v2/users instead')]
public function index()
{
    // ...
}

2. Customizing Documentation

Grouping Endpoints: Use the #[Group] attribute to organize endpoints into logical sections:
```
#[Group('Admin')]
public function adminDashboard()
{
    // ...
}
```

Adding Descriptions: Use #[Description] to add markdown-formatted descriptions:

use Knuckles\Scribe\Attributes\Description;

#[Description('Retrieves a paginated list of users. Supports filtering by `role` and `status`.')]
public function index()
{
    // ...
}

Custom Examples: Override example responses via the #[Example] attribute:

use Knuckles\Scribe\Attributes\Example;

#[Example(
    status: 200,
    body: ['message' => 'User created successfully']
)]
public function store()
{
    // ...
}

3. Advanced Features

Authentication: Scribe supports documenting authenticated endpoints. Configure in config/scribe.php:

'auth' => [
    'headers' => [
        'Authorization' => 'Bearer {token}',
    ],
],

Use the #[Auth] attribute to mark endpoints requiring auth:

use Knuckles\Scribe\Attributes\Auth;

#[Auth]
public function sensitiveData()
{
    // ...
}

Webhooks: Document webhook endpoints with #[Webhook]:

use Knuckles\Scribe\Attributes\Webhook;

#[Webhook]
public function handleStripeWebhook()
{
    // ...
}

Custom Strategies: Extend Scribe’s behavior by creating custom strategies (e.g., for non-standard request handling):

// app/Scribe/CustomRequestStrategy.php
namespace App\Scribe;

use Knuckles\Scribe\Extractors\Attributes\BodyParam;
use Knuckles\Scribe\Extractors\RequestExtractor;

class CustomRequestStrategy extends RequestExtractor
{
    public function extract(): array
    {
        // Custom logic here
        return [];
    }
}

'strategies' => [
    \App\Scribe\CustomRequestStrategy::class,
],

4. Integration with CI/CD

Automated Documentation Updates: Add a step to your CI pipeline (e.g., GitHub Actions) to regenerate docs on every push:

# .github/workflows/docs.yml
name: Generate API Docs
on: [push]
jobs:
  generate-docs:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: shivammathur/setup-php@v2
        with:
          php-version: '8.2'
      - run: composer install -n --prefer-dist
      - run: php artisan scribe:generate
      - uses: actions/upload-artifact@v3
        with:
          name: api-docs
          path: storage/app/public/scribe/

Deploying Documentation: Deploy the generated scribe folder to a static hosting service (e.g., Netlify, Vercel) or serve it via your Laravel app.

Daily Developer Workflow

Local Development:
- Regenerate docs after changes:
```
php artisan scribe:generate --watch
```
  (Watches for route/controller changes and regenerates docs.)
Testing:
- Use the "Try It Out" panel to test endpoints interactively.
- Validate Postman collections by importing them into Postman.
Collaboration:
- Share the storage/app/public/scribe/index.html file with teammates or clients.
- Use the OpenAPI spec (storage/app/public/scribe/openapi.json) for integration testing.
Maintenance:
- Update descriptions or examples as the API evolves.
- Deprecate old endpoints using #[Deprecated] and mark them in the UI.

Gotchas and Tips

Common Pitfalls

1. Route Discovery Issues

Problem: Scribe misses certain routes (e.g., named routes or dynamic routes).
Solution:
- Ensure routes are defined in routes/api.php or routes/web.php.
- For dynamic routes, use explicit route names:
```
Route::get('/users/{user}', [UserController::class, 'show'])->name('users.show');
```
- If using API resource routes, ensure they’re discovered by Laravel’s router.
Debugging: Run php artisan route:list to verify routes are registered. Use the --verbose flag to check middleware and namespaces.

2. Validation Rule Extraction

Problem: Complex validation rules (e.g., nested arrays, custom validators) aren’t parsed correctly.

Solution:

Simplify rules or use #[BodyParam]/#[QueryParam] for explicit documentation:

use Knuckles\Scribe\Attributes\BodyParam;

#[BodyParam(name: 'user', type: 'object', attributes: [
    new BodyParam(name: 'name', type: 'string', description: 'User name'),
    new BodyParam(name: 'roles', type: 'array', description: 'User roles', attributes: [
        new BodyParam(name: 'role', type: 'string'),
    ]),
])]
public function store(Request $request)
{
    // ...
}

For custom validators, extend the

Scribe Laravel Package