<p>Laravel API Inspector, Laravel rotalarınızdan, FormRequest doğrulama kurallarından ve API Resources'dan otomatik olarak API belgelerini üretir. Postman ve Swagger kombinasyonu gibidir, ancak Laravel ile derinlemesine entegre edilmiştir.</p>
<p>Projenin git deposu <a href="https://github.com/irabbi360/laravel-api-inspector" target="_blank" rel="noopener noreferrer">burada</a> bulunabilir.</p>
<p><strong>Özellikler</strong></p>
<p>✨ Otomatik FormRequest Kurallarını Ayıklama - Laravel doğrulama kurallarını kapsamlı belgelere dönüştürür<br/>📮 Postman Koleksiyonları Üretme - Örneklerle birlikte kullanıma hazır Postman koleksiyonları oluşturur<br/>📖 OpenAPI/Swagger Spesifikasyonları - Swagger UI ve Redoc gibi araçlar için OpenAPI 3.0 formatında dışa aktarım<br/>📄 HTML Belgeleri - Örneklerle birlikte güzel bir şekilde otomatik oluşturulmuş HTML belgeleri<br/>🔍 API Kaynaklarını Tespit Etme - API kaynaklarınızdan yanıt yapılarını çıkarır<br/>💾 Yanıt Örneklerini Kaydetme - JSON yanıtlarını dosyalara otomatik olarak kaydeder<br/>🔐 Kimlik Doğrulama Desteği - Korunan rotaları otomatik olarak tespit eder ve kimlik doğrulama başlıklarını ekler.</p>
<p><strong>Kurulum</strong><br/>Gereksinimler</p>
<p>PHP: 8.1 veya üstü<br/>Laravel: 10.0 veya üstü<br/>Veritabanı: MySQL 5.7+ / PostgreSQL 10+ / SQLite 3.8+</p>
<p>Sadece iki komutla başlayabilirsiniz:</p>
<p><code>composer require irabbi360/laravel-api-inspector</code></p>
<p>İnteraktif yükleyiciyi çalıştırın:</p>
<p><code>php artisan api-inspector:install</code></p>
<p>Hızlı Başlangıç<br/>Tarayıcıda Belgeleri Görüntüle<br/>Belgeleri oluşturduktan sonra, şu adrese gidin:</p>
<p><code>http://localhost:8000/api-docs</code><br/>Doğrulama Kuralları ile Bir FormRequest Oluşturun<br/></p>
<div class="highlight js-code-highlight">
<pre class="highlight plaintext"><code><?php namespace App\Http\Requests;
use Illuminate\Foundation\Http\FormRequest;
class StoreUserRequest extends FormRequest
{
public function rules()
{
return [
‘name’ => ‘required|string|max:255′,
’email’ => ‘required|email|unique:users’,
‘password’ => ‘required|min:8|confirmed’,
‘age’ => ‘integer|min:18|max:100’,
];
}
}
<p>Kontrolcünüzde FormRequest’i Kullanın<br/></p>
<div class="highlight js-code-highlight">
<pre class="highlight plaintext"><code><?php namespace App\Http\Controllers;
use App\Http\Requests\StoreUserRequest;
class UserController extends Controller
{
public function store(StoreUserRequest $request)
{
return response()->json([
‘success’ => true,
‘message’ => ‘Kullanıcı başarıyla oluşturuldu’,
‘data’ => User::create($request->validated()),
], 201);
}
}
<p>Kontrolcünüzde Aksiyonları Kullanın<br/></p>
<div class="highlight js-code-highlight">
<pre class="highlight plaintext"><code><?php namespace App\Http\Controllers;
use App\Actions\CreateUser;
class UserController extends Controller
{
public function store(Request $request, CreateUser $action)
{
$action->create($request->all());
return response()->json([
'success' => true,
'message' => 'Kullanıcı başarıyla oluşturuldu',
], 201);
}
}
<p>Otomatik Yanıt Şeması Oluşturma. Artık kontrolcü yöntemlerinize not ekleyebilirsiniz:<br/></p>
<div class="highlight js-code-highlight">
<pre class="highlight plaintext"><code><?php /
* Kullanıcı profilini al
* @LAPIresponsesSchema ProfileResource
*/
public function show(User $user)
{
return new ProfileResource($user);
}
<p>Ya da not eklemeden, dönüş türünden otomatik olarak algılayabilirsiniz:<br/></p>
<div class="highlight js-code-highlight">
<pre class="highlight plaintext"><code><?php public function show(User $user): ProfileResource
{
return new ProfileResource($user);
}
<?php
/
- Sayfalama ile kullanıcı listesini al
- @LAPIpagination
*/
public function index()
{
$users = User::latest()->paginate();
return ProfileResource::collection($users);
}
/
* Kullanıcı listesi
* @LAPIQueryParams {
* "name": {"type": "string", "required": true, "description": "Kullanıcı adını filtrele"},
* "page": {"type": "integer", "required": false, "example": 1},
* "limit": {"type": "integer", "required": false}
* }
*/
<p>public function index(Request $request) { ... }<br/>veya<br/></p>
<div class="highlight js-code-highlight">
<pre class="highlight plaintext"><code><?php /
✅ @LAPIresponsesSchema ResourceName’i doküman bloklarından ayıkla
✅ @LAPIpagination’ı doküman bloklarından ayıkla
✅ @LAPIQueryParams sorgu parametrelerini doküman bloklarından ayıkla
✅ Cevap şemasını JSON formatında göster
✅ İçi içe geçmiş kaynakları özyinelemeli olarak ele al
✅ Sonsuz döngüleri önlemek için derinlik limitleri kullan
- Tarayıcıda Görüntüle
Oluşturduktan sonra, belgelerinizi otomatik olarak görüntüleyin:
http://localhost:8000/api-docs
Bu kadar! 🎉 API’niz artık belgelenmiş ve tarayıcıdan erişilebilir.
API Koleksiyonunu Oluştur veya İndir
Komut, belgeleri üç formatta oluşturur:
API İstatistikleri – http://localhost:8000/api-docs/stats (tarayıcıda görüntüle) İstatistikler sayfasından Postman API Koleksiyonlarını ve OpenAPI Spesifikasyonunu indirebilirsiniz
Dosyalar ayrıca storage/api-docs/ dizinine yedekler olarak kaydedilir.
Konfigürasyon
config/api-inspector.php dosyasını düzenleyin:
return [
'enabled' => true,
'save_responses' => true, // Örnek yanıtları JSON dosyalarına kaydet
'save_responses_driver' => 'json', // 'cache' veya 'json' - 2. Aşama
'middleware_capture' => true, // Gerçek yanıtları yakala - 2. Aşama
'response_ttl' => 3600, // Cache TTL saniye cinsinden (1 saat) - 2. Aşama
'auth' => [
'type' => 'bearer',
'header' => 'Authorization'
],
'response_path' => storage_path('api-docs'),
];
Çalışma Zamanı Yanıtı Yakalama & Önbellekleme
Orta Katman Yanıt Yakalama
Çalışan uç noktalarınızdan gerçek API yanıtlarını otomatik olarak yakalayın:
// Orta katman otomatik olarak başarılı (2xx) JSON yanıtlarını yakalar
// config/api-inspector.php dosyasındaki yapılandırma:
'middleware_capture' => true, // Yanıt yakalamayı etkinleştir
'save_responses_driver' => 'json', // Dosyalara veya önbelleğe kaydet
'response_ttl' => 3600, // Önbellek süre sonu
Özellikler:
✅ Gerçek API yanıtlarını otomatik olarak yakalar
✅ Sadece başarılı (2xx) yanıtları yakalar
✅ Sadece API rotalarını hedefler (yapılandırılabilir prefix)
✅ Yanıtları JSON dosyalarına veya Laravel önbelleğine kaydeder
✅ Yeni bilgiler için kaydetme zaman damgasını içerir
✅ Hata yönetimi (API’nizi bozmaz)
YanıtCache Sınıfını Kullanma
Önbelleğe alınan yanıtları programlı olarak yönetin:
use Irabbi360\LaravelApiInspector\Support\ResponseCache;
class YourController extends Controller
{
public function someAction(ResponseCache $responseCache)
{
// Bir yanıtı kaydet
$responseCache->store('api/users/index', 200, [
'data' => [/ ... /],
'success' => true
]);
// Önbelleğe alınmış bir yanıtı al
$cached = $responseCache->get('api/users/index', 200);
// Yanıtın önbellekte olup olmadığını kontrol et
if ($responseCache->has('api/users/index', 200)) {
// Önbellek yanıtını kullan
}
// Bir rota için tüm yanıtları al
$allResponses = $responseCache->getForRoute('api/users');
// Bir rota için yanıtları temizle
$responseCache->clearForRoute('api/users');
// Tüm önbelleğe alınmış yanıtları temizle
$responseCache->clearAll();
}
}
<p><strong>Depolama Sürücüleri</strong><br/>JSON Sürücüsü (geliştirme/üretim için önerilir)<br/></p>
<div class="highlight js-code-highlight">
<pre class="highlight plaintext"><code>'save_responses_driver' => 'json'
// storage/api-docs/cached-responses/ dizinine depolar
// Önbellek sıfırlamalarında da kalıcı
// Takım paylaşımı için daha iyi
Cache Sürücüsü (performans için önerilir)
‘save_responses_driver’ => ‘cache’
// Yapılandırdığınız önbellek arka ucu (redis, memcached, vb.) kullanır
// Daha hızlı erişim
// Her yanıt için yapılandırılabilir TTL
<p><strong>Örnek İş Akışı</strong><br/>Orta katman yakalamayı etkinleştirin:<br/>config/api-inspector.php dosyasında<br/><code>'middleware_capture' => true,</code></p>
<p>API’nize şu istekleri yapın:</p>
<p><code>curl -X GET http://localhost:8000/api/users</code><br/>
<code>curl -X POST http://localhost:8000/api/users -H "Content-Type: application/json" -d '{"name":"John","email":"[email protected]"}'</code></p>
<p>Yanıtlar otomatik olarak yakalanır:</p>
<pre><code>storage/api-docs/cached-responses/
├── api_response:api_users:200.json
├── api_response:api_users:201.json
└── …
Belgelerde yakalanan yanıtları kullanın:
Postman koleksiyonu artık gerçek örnek yanıtlarını içerir
OpenAPI spesifikasyonu gerçek yanıt şemalarını içerir
HTML belgeleri API’nizden gerçek verileri gösterir
Aşama 3: Gösterge Paneli, Analitik & Gelişmiş Özellikler
API Analitik & İzleme
API performansını otomatik olarak izleyin:
// config/api-inspector.php dosyasında analitikleri etkinleştirin:
'analytics' => [
'enabled' => true,
'track_response_time' => true,
'track_memory_usage' => true,
'track_errors' => true,
'retention_days' => 30,
'track_only_uri_start_with' => 'api/',
]
<p>Etkinleştirdikten sonra, paket, veri tabanına istek ölçümlerini loglayacaktır. API rotalarınıza orta katmanı eklemeyi unutmayın:</p>
<p>Irabbi360\LaravelApiInspector\Middleware\ApiInspectorAnalyticsMiddleware;<br/><strong>Özellikler:</strong></p>
<p>✅ Gerçek zamanlı istek izleme<br/>✅ Yanıt süresi analizi<br/>✅ Bellek kullanım izleme<br/>✅ Hata oranı hesaplama<br/>✅ Performans trendleri ve içgörü<br/>✅ Otomatik veri saklama yönetimi<br/>Web UI Gösterge Paneli<br/>/api-docs/stats adresine erişebilirsiniz:<br/></p>
<p><strong>Gösterge Paneli İçeriği:</strong></p>
<p>Gerçek zamanlı istek ölçümleri<br/>Yanıt süresi dağılım grafikleri<br/>Hata oranı izleme<br/>Durum kodu istatistikleri<br/>En yavaş rotaların belirlenmesi<br/>Son hataların izlenmesi<br/>Rota düzeyinde performans analizi<br/>Özelleştirilebilir zaman aralıkları (1s, 24s, 7g, 30g)<br/><code>'dashboard' => [<br/>'enabled' => true,<br/>'auth_middleware' => ['web'], // Gösterge paneli erişimini korumak<br/>]</code></p>
<p>Güzel, duyarlı bir belge sitesi içermektedir:</p>
<p>İstek/yanıt örnekleri<br/>Parametre açıklamaları<br/>Kimlik doğrulama göstergeleri<br/>Arama ve navigasyon<br/><strong>Örnekler</strong><br/>FormRequest’ten Belgelemeye<br/>FormRequest’iniz:</p>
<div class="highlight js-code-highlight">
<pre class="highlight plaintext"><code>
’email’ => ‘required|email’,
‘age’ => ‘integer|min:18|max:100’
