Laravel API Inspector: Route ve FormRequest'ten Otomatik Dokümantasyon

API yazdınız, Postman'de test ettiniz, çalışıyor. Sonra ekip arkadaşınız soruyor: "Bu endpoint ne alıyor, ne dönüyor?" ve siz Slack'te JSON örnekleri yapıştırmaya başlıyorsunuz.

Ya da daha kötüsü: Swagger/OpenAPI dosyasını elle yazıyorsunuz. Route ekliyorsunuz ama Swagger'ı güncellemeyi unutuyorsunuz. Bir ay sonra dokümantasyon ile gerçek API arasında dağlar kadar fark oluşuyor.

Laravel API Inspector tam bu sorunu çözüyor. Route'larınızdan, FormRequest kurallarınızdan ve API Resource'larınızdan otomatik dokümantasyon üretiyor. Postman collection'ı, OpenAPI spec'i, HTML dokümantasyonu — hepsi tek komutla.

Ne İş Yapıyor?

API Inspector Laravel uygulamanızı analiz ediyor ve şunları otomatik çıkarıyor:

• Route'lardan endpoint listesi, HTTP method'ları, middleware bilgileri
• FormRequest'lerden request body şeması (validation rule'larını okuyarak)
• API Resource'lardan response yapısı
• Runtime'da gerçek response örnekleri (middleware ile yakalayarak)

Sonuç olarak elinizde:

• Tarayıcıda açılabilen HTML dokümantasyon sayfası
• Postman'e import edilebilen collection dosyası
• OpenAPI 3.0 spec dosyası (Swagger UI, Redoc ile kullanılabilir)
• Response time, memory usage gibi analitik verileri

Kurulum

composer require irabbi360/laravel-api-inspector
php artisan api-inspector:install

Bu kadar. Tarayıcıda http://localhost:8000/api-docs açın, API dokümantasyonunuz hazır.

FormRequest'ten Otomatik Şema Üretimi

API Inspector'ın en güçlü özelliği FormRequest kurallarını otomatik parse etmesi. Zaten yazdığınız validation kuralları dokümantasyona dönüşüyor.

namespace App\Http\Requests;

use Illuminate\Foundation\Http\FormRequest;

class StoreUserRequest extends FormRequest
{
    public function rules(): array
    {
        return [
            'name' => 'required|string|max:255',
            'email' => 'required|email|unique:users',
            'password' => 'required|min:8|confirmed',
            'age' => 'integer|min:18|max:100',
            'role' => 'required|in:admin,editor,viewer',
            'avatar' => 'nullable|image|max:2048',
        ];
    }
}

Bu kurallardan API Inspector şu bilgileri çıkarıyor:

confirmed kuralını görünce otomatik password_confirmation alanı ekliyor. in: kuralını enum'a çeviriyor. email kuralını format olarak işaretliyor. Elle yazsanız 10 dakika, otomatik 0 saniye.

Controller'da Kullanım

Controller'ınız zaten FormRequest kullanıyorsa ekstra bir şey yapmanıza gerek yok:

namespace App\Http\Controllers;

use App\Http\Requests\StoreUserRequest;
use App\Http\Resources\UserResource;
use App\Models\User;

class UserController extends Controller
{
    public function store(StoreUserRequest $request)
    {
        $user = User::create($request->validated());

        return new UserResource($user);
    }

    /**
     * @LAPIresponsesSchema UserResource
     */
    public function show(User $user)
    {
        return new UserResource($user);
    }

    /**
     * @LAPIpagination
     */
    public function index()
    {
        return UserResource::collection(
            User::latest()->paginate()
        );
    }
}

Birkaç annotation var:

• @LAPIresponsesSchema UserResource — Response yapısını belirtir
• @LAPIpagination — Sayfalama bilgisini ekler
• Return type olarak UserResource yazarsanız annotation'a gerek kalmaz

Query Parameter Dokümantasyonu

GET endpoint'lerinin query parametrelerini de belgeleyebilirsiniz. Üç farklı format destekliyor:

JSON format (detaylı):

/**
 * @LAPIQueryParams {
 *   "name": {"type": "string", "required": true, "description": "İsme göre filtrele"},
 *   "page": {"type": "integer", "required": false, "example": 1},
 *   "per_page": {"type": "integer", "required": false}
 * }
 */
public function index() { ... }

Kısa format:

/**
 * @LAPIQueryParams name:string required, page:integer optional, per_page:integer optional
 */

Basit format:

/**
 * @LAPIQueryParams name, page, per_page, status
 */

Hangisini kullanacağınız size kalmış. Basit format hızlı, JSON format detaylı.

Runtime Response Yakalama

API Inspector bir middleware ile gerçek API response'larını yakalayıp kaydedebilir. Böylece dokümantasyondaki örnekler gerçek veriyle oluşur — elle JSON yazmak yok.

config/api-inspector.php'de:

return [
    'enabled' => true,
    'save_responses' => true,
    'save_responses_driver' => 'json',
    'middleware_capture' => true,
    'response_ttl' => 3600,
    'auth' => [
        'type' => 'bearer',
        'header' => 'Authorization',
    ],
    'response_path' => storage_path('api-docs'),
];

middleware_capture açıkken başarılı (2xx) JSON response'lar otomatik storage/api-docs/ klasörüne kaydedilir. Bir kez endpoint'i çağırırsanız gerçek response örneği dokümantasyonda görünür.

Cache yönetimi için:

use Irabbi360\LaravelApiInspector\Support\ResponseCache;

// Manuel kaydet
$responseCache->store('api/users/index', 200, ['data' => [...]]);

// Cache'i temizle
$responseCache->clearForRoute('api/users');
$responseCache->clearAll();

Analitik Dashboard

API Inspector sadece dokümantasyon değil, analitik de sunuyor. Config'de açın:

'analytics' => [
    'enabled' => true,
    'track_response_time' => true,
    'track_memory_usage' => true,
    'track_errors' => true,
    'retention_days' => 30,
    'track_only_uri_start_with' => 'api/',
],

API route'larınıza middleware ekleyin:

Route::middleware([
    'api',
    \Irabbi360\LaravelApiInspector\Middleware\ApiInspectorAnalyticsMiddleware::class,
])->group(function () {
    // API route'larınız
});

http://localhost:8000/api-docs/stats adresinde göreceğiniz dashboard:

• Request metrikleri (toplam istek, ortalama response time)
• Response time dağılım grafikleri
• Error rate izleme
• HTTP status code istatistikleri
• En yavaş route'lar
• Son hatalar
• Route bazlı performans analizi

Bu, production'da API'nizin sağlığını izlemek için çok değerli. Laravel Telescope veya Pulse ile birlikte kullanabilirsiniz ama API Inspector'ın avantajı sadece API endpoint'lerine odaklanması.

Postman ve OpenAPI Export

http://localhost:8000/api-docs sayfasında indirme butonları var:

• Postman Collection — Doğrudan Postman'e import edin, tüm endpoint'ler hazır
• OpenAPI 3.0 Spec — Swagger UI, Redoc veya başka bir araçla kullanın

Dosyalar storage/api-docs/ klasörüne kaydedilir.

Postman collection'ında her endpoint için:

• URL ve HTTP method
• Request body örnekleri (FormRequest'ten)
• Auth header'ları (korumalı route'lar için)
• Response örnekleri (runtime'dan yakalanmışsa)

Validation Kuralları Eşleştirme

API Inspector Laravel validation kurallarını şöyle dönüştürüyor:

Bu eşleştirme sayesinde validation kurallarınız yazıldığı anda dokümantasyon da hazır oluyor. DRY prensibinin güzel bir örneği — aynı bilgiyi iki kez yazmıyorsunuz.

Ne Zaman Kullanmalı?

Kullanın:

• Takımda birden fazla geliştirici varsa ve API dokümantasyonu paylaşmanız gerekiyorsa
• Frontend ekibiyle çalışıyorsanız (React, Vue, Flutter) ve endpoint detaylarını paylaşmanız gerekiyorsa
• Müşteriye veya üçüncü parti entegrasyona API dokümantasyonu vermeniz gerekiyorsa
• API performansını izlemek istiyorsanız

Gerekmeyebilir:

• Tek başınıza küçük bir proje geliştiriyorsanız
• Sadece admin panel API'si varsa ve frontend'i kendiniz yazıyorsanız
• Zaten Scribe veya L5-Swagger kullanıyorsanız ve memnunsanız

Scribe ve Swagger Alternatifleriyle Karşılaştırma

API Inspector'ın farkı analitik dashboard ve runtime response yakalama. Scribe daha olgun ve topluluk desteği daha geniş. İhtiyacınıza göre seçin.

Sonuç

API dokümantasyonu yazmak sıkıcı ama gerekli bir iş. API Inspector bu yükü neredeyse sıfıra indiriyor. FormRequest kurallarınız zaten var, route'larınız zaten var — Inspector bunları birleştirip profesyonel bir dokümantasyon çıkarıyor.

Kurulumu 2 dakika. Deneyip beğenmezseniz composer remove ile kaldırın, hiçbir iz bırakmaz.