The Postman Fallacy

When building a B2B SaaS platform at Smart Tech Devs, your API is a core product. If enterprise clients are integrating with your system, they need flawless, accurate documentation. The standard approach for many teams is to manually maintain a Postman collection or a Swagger file.

The problem? The moment a developer adds a new required field to a Laravel FormRequest and deploys the code, the manual API documentation becomes instantly outdated. The client integrates using the old docs, their requests fail with a 422 error, and your support inbox floods. Manual documentation is a liability. You must generate your documentation directly from your codebase.

Enter Scribe: Code-Driven Documentation

To eliminate documentation drift, we use a tool called Scribe for Laravel. Scribe analyzes your routes, reads your controller methods, parses your FormRequests, and automatically generates beautiful, interactive HTML documentation (and an OpenAPI spec) without you having to write a single YAML file.

Architecting Auto-Documented Endpoints

Scribe is incredibly smart. It reads standard PHP DocBlocks and Laravel validation rules to figure out exactly what your API expects and returns.

namespace App\Http\Controllers\Api;

use App\Http\Controllers\Controller;
use App\Http\Requests\StoreInvoiceRequest;
use App\Models\Invoice;

/**
 * @group Billing Integration
 * * APIs for managing tenant invoices and billing cycles.
 */
class InvoiceController extends Controller
{
    /**
     * Create a new invoice.
     *
     * This endpoint allows external systems to generate an invoice for an active tenant.
     * The total amount will be calculated automatically based on the line items.
     *
     * @response 201 {
     * "id": 9482,
     * "tenant_id": 105,
     * "status": "draft",
     * "created_at": "2026-05-18T10:00:00.000000Z"
     * }
     */
    public function store(StoreInvoiceRequest $request)
    {
        // Your business logic here...
        $invoice = Invoice::create($request->validated());

        return response()->json($invoice, 201);
    }
}

Extracting Rules from FormRequests

The true power of Scribe lies in how it parses StoreInvoiceRequest. You do not need to manually document every single body parameter. Scribe reads the rules array and automatically generates the documentation table showing what fields are required, what type they are, and any specific validation constraints (like max length or regex).

namespace App\Http\Requests;

use Illuminate\Foundation\Http\FormRequest;

class StoreInvoiceRequest extends FormRequest
{
    public function rules(): array
    {
        return [
            // Scribe sees this and documents: "tenant_id (integer, required)"
            'tenant_id' => ['required', 'integer', 'exists:tenants,id'],
            
            // Scribe sees this and documents: "due_date (date, optional). Must be after today."
            'due_date' => ['nullable', 'date', 'after:today'],
            
            // Scribe sees this and documents: "currency (string, required). Example: USD, EUR"
            'currency' => ['required', 'string', 'in:USD,EUR,GBP'],
        ];
    }
}

The Engineering ROI

By running php artisan scribe:generate during your CI/CD deployment pipeline, you guarantee that your public API documentation is perfectly synchronized with your actual production code 100% of the time. You eliminate human error, save your developers hours of tedious manual writing, and provide your B2B clients with the premium, reliable integration experience they expect.