Scribe Laravel Package

Getting Started

Minimal Setup

1. Installation:

   composer require knuckleswtf/scribe
   

   Publish the config file:

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

2. First Run: Generate documentation for all routes:

   php artisan scribe:generate
   

   Access the generated HTML at public/docs/index.html (or your configured output path).

3. Quick Test: Visit http://your-app.test/docs to see the interactive documentation with "Try It Out" panels.

First Use Case

Document a new API endpoint:

// routes/api.php
Route::get('/users/{id}', [UserController::class, 'show'])
    ->middleware('auth:sanctum')
    ->name('users.show');

Scribe automatically detects this route and generates:

• Endpoint URL
• Authentication requirements (from middleware)
• Sample responses (if you configure response generation)

Implementation Patterns

Core Workflows

1. Route Documentation

• Automatic Discovery: Scribe scans all registered routes in routes/ and app/Http/Controllers/.
• Customization:

  // app/Http/Controllers/UserController.php
  use Knuckles\Scribe\Attributes\Deprecated;
  use Knuckles\Scribe\Attributes\BodyParam;
  
  #[Deprecated('Use /users/{id}/profile instead')]
  public function show(int $id) { ... }
  
  #[BodyParam(name: 'name', type: 'string', description: 'User name')]
  public function update(Request $request) { ... }
  

2. Response Generation

• Dynamic Responses: Use #[Response] attributes or configure in scribe.php:

  'responses' => [
      'users.show' => [
          '200' => [
              'description' => 'Returns a user',
              'content' => [
                  'application/json' => [
                      'schema' => [
                          'type' => 'object',
                          'properties' => [
                              'id' => ['type' => 'integer'],
                              'name' => ['type' => 'string']
                          ]
                      ]
                  ]
              ]
          ]
      ]
  ],
  

• API Resources: Scribe automatically detects Illuminate\Http\Resources\Json\JsonResource and generates schemas.

3. Validation Rules

• Form Requests: Extract rules from FormRequest classes:

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

• Manual Rules: Define in scribe.php:

  'parameters' => [
      'users.store' => [
          'body' => [
              'name' => ['type' => 'string', 'description' => 'User name'],
              'email' => ['type' => 'string', 'format' => 'email']
          ]
      ]
  ],
  

4. Authentication

• Middleware Detection: Scribe automatically lists middleware (e.g., auth:sanctum).
• Custom Security Schemes: Define in scribe.php:

  'security' => [
      'bearerAuth' => [
          'type' => 'http',
          'scheme' => 'bearer',
          'bearerFormat' => 'JWT'
      ]
  ],
  

5. Custom Endpoints

Add undocumented routes manually:

'scribe' => [
    'endpoints' => [
        [
            'method' => 'GET',
            'uri' => '/admin/dashboard',
            'description' => 'Admin dashboard',
            'auth' => ['admin']
        ]
    ]
],

Integration Tips

1. CI/CD Pipeline

Add to your deployment script:

php artisan scribe:generate --output=docs
git add docs
git commit -m "Update API docs"

2. Versioned Documentation

Use Laravel Mix or Vite to serve versioned docs:

// vite.config.js
import { defineConfig } from 'vite';
import { scribePlugin } from 'vite-plugin-scribe';

export default defineConfig({
  plugins: [
    scribePlugin({
      versions: ['v1', 'v2'],
      outputDir: 'docs'
    })
  ]
});

3. Postman/OpenAPI Export

Generate specs during deployment:

php artisan scribe:generate --export=postman,openapi

• Outputs:
  • public/docs/openapi.json (OpenAPI 3.0/3.1)
  • public/docs/Postman Collection.json

4. Testing Documentation

Add to your test suite:

// tests/Feature/ApiDocumentationTest.php
public function test_api_docs_generate()
{
    $this->artisan('scribe:generate')
         ->assertExitCode(0)
         ->expectsOutput('Generated API documentation');
    $this->assertFileExists(public_path('docs/index.html'));
}

5. Theming

Customize the UI by extending the default theme:

1. Copy vendor/knuckleswtf/scribe/resources/views to resources/views/vendor/scribe.
2. Override templates (e.g., endpoint.blade.php).

Gotchas and Tips

Pitfalls

1. Circular Dependencies in Responses

• Issue: Complex Eloquent relationships may cause infinite loops.
• Fix: Use #[Response] with explicit schemas or configure ignore_relationships in scribe.php:

  'responses' => [
      'users.show' => [
          '200' => [
              'ignore_relationships' => ['posts', 'comments']
          ]
      ]
  ],
  

2. Middleware Not Detected

• Issue: Custom middleware isn’t listed in docs.
• Fix: Ensure middleware is registered in app/Http/Kernel.php and use #[Deprecated] or #[Auth] attributes:

  use Knuckles\Scribe\Attributes\Auth;
  
  #[Auth('api')]
  public function sensitiveEndpoint() { ... }
  

3. Validation Rules Not Parsed

• Issue: Custom validator rules (e.g., unique:users,email) aren’t documented.
• Fix: Extend the validator parser or define manually:

  'parameters' => [
      'users.store' => [
          'body' => [
              'email' => [
                  'type' => 'string',
                  'format' => 'email',
                  'description' => 'Must be unique in users table'
              ]
          ]
      ]
  ],
  

4. Performance with Large APIs

• Issue: Generation is slow for APIs with 100+ endpoints.
• Fix:
  • Use --parallel flag:

    php artisan scribe:generate --parallel
    

  • Exclude unused routes in scribe.php:

    'ignore_routes' => [
        'admin.*',
        'web.*'
    ],
    

5. Dynamic Responses Failing

• Issue: #[Response] fails with "Model not found" errors.
• Fix: Mock dependencies or use factories:

  // config/scribe.php
  'factories' => [
      App\Models\User::class => App\Models\UserFactory::new()
  ],
  

Debugging Tips

1. Verbose Output

Run with -v for detailed logs:

php artisan scribe:generate -v

2. Dry Run

Test changes without overwriting:

php artisan scribe:generate --dry-run

3. Inspect Generated OpenAPI

Validate the spec using Swagger Editor:

php artisan scribe:generate --export=openapi
open public/docs/openapi.json

4. Common Errors

Extension Points

1. Custom Strategies

Extend Knuckles\Scribe\Strategies\Strategy to add new data sources:

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

use Knuckles\Scribe\Strategies\Strategy;

class CustomStrategy extends Strategy
{
    public function getEndpoints(): array
    {
        return [
            [
                'method' => 'GET',
                'uri' => '/custom',
                'description' => 'Custom endpoint'
            ]
        ];
    }
}

Register in scribe.php:

'strategies' => [
    \App\Scribe