Swagger Notları Yazmak Zor. Ya Bunu Yapmanıza Gerek Kalmazsa?
Gerçekçi olmak gerekirse — kaç kez:
@OA\Getnotları yüzünden API belgelerini atladınız?- Gerçek iş mantığından daha fazla Swagger yorumları yazdınız mı?
- “Sonra ekleriz” diyerek hiç belgesiz bir API gönderdiniz (eklemediniz tabi ki)?
- Her zaman 3 endpoint geride kalan bir Postman koleksiyonu manuel olarak mı korudunuz?
Peki ya Laravel uygulamanız denetleyicilerinizi tarayıp, FormRequest kurallarınızı okuyup, tamamen otomatik bir Swagger UI oluşturabilirse?
Hiçbir @OA\ notu yok. Hiçbir YAML dosyası yok. Hiçbir yapılandırma yok. Sadece mevcut kodunuz.
Tanıtım: Laravel API Cevap Oluşturucu
composer require stackmasteraliza/laravel-api-response
v4.7.0 | Laravel 10, 11 & 12 | PHP 8.1+ | MIT Licences
GitHub |
Packagist
Tümleşik bir Laravel API araç takımı:
- Otomatik oluşturulmuş Swagger/OpenAPI belgeleri — hiçbir not yok
- Postman & Insomnia’ya bir tıklama ile dışa aktarma
- Standartlaştırılmış JSON yanıtları
- WebSocket testi ile birlikte
- API sürümlemesi hemen pakette mevcut
Hiçbir yapılandırma gerekli değil.
Kurulum (30 Saniye)
composer require stackmasteraliza/laravel-api-response
Bu kadar. Yapılandırma yayını yok. Migration yok. Kurulum sihirbazı yok.
Swagger belgeleriniz zaten /api-docs adresinde canlı.
Otomatik Olarak Oluşturulan Swagger Belgeleri (Ana Olay)
Buraya neden geldiğinizi biliyoruz. Tek bir @OA\ notu yazmıyorsunuz.
Paket, denetleyicilerinizi tarar, ApiResponse::success() ve ApiResponse::created() gibi yanıt yöntemlerini tespit eder, FormRequest doğrulama kurallarınızı okur ve tam bir OpenAPI 3.0 spesifikasyonu oluşturur — otomatik olarak.
/api-docs adresini ziyaret ettiğinizde, aşağıdakileri alırsınız:
- Hafif ve modern Swagger UI ile karanlık/açık tema geçişi
- Tüm endpoint’ler doğru HTTP yöntemleriyle belgelenmiştir
- İstek gövde şemaları FormRequest kurallarınızdan otomatik olarak oluşturulur
- Yanıt şemaları, gerçek yanıt yapınıza uygundur
- Deneyin işlevi – doğrudan tarayıcıdan endpoint’leri test edin
Her Şeyi Nasıl Tespit Ediyor?
// Paket denetleyicinizde bunu görüyor...
public function store(StoreUserRequest $request)
{
$user = User::create($request->validated());
return ApiResponse::created($user, 'User created');
}
// ...FormRequest kurallarınızı okur...
class StoreUserRequest extends FormRequest
{
public function rules(): array
{
return [
'name' => 'required|string|max:255',
'email' => 'required|email|unique:users',
'password' => 'required|min:8',
];
}
}
Sonuç: Swagger’da tam olarak belgelenmiş bir POST endpoint’i ile istek gövde şeması, gerekli alanlar, doğrulama türleri ve 201 Created yanıtını alırsınız — hepsini tek bir doküman yorumu yazmadan.
Daha Fazla Kontrol Mü İstiyorsunuz? PHP Özelliklerini Kullanın
use Stackmasteraliza\ApiResponse\Attributes\ApiEndpoint;
use Stackmasteraliza\ApiResponse\Attributes\ApiRequestBody;
[ApiEndpoint(
summary: 'Yeni bir kullanıcı oluştur',
description: 'Yeni bir kullanıcı hesabı kaydedin',
tags: ['Kullanıcılar']
)]
[ApiRequestBody(
properties: [
'name' => 'string',
'email' => 'string',
'password' => 'string',
],
required: ['name', 'email', 'password']
)]
public function store(StoreUserRequest $request): JsonResponse
{
$user = User::create($request->validated());
return ApiResponse::created($user, 'User created');
}
Özellikler isteğe bağlıdır — yalnızca özetler, açıklamalar eklemek veya otomatik olarak tespit edilen şemaları geçersiz kılmak istediğinizde kullanın.
Postman & Insomnia’ya Bir Tıklama ile Dışa Aktarma
Swagger UI’den tüm API belgenizi dışa aktarın:
| Format | Kullanım Durumu |
|---|---|
| Postman | Doğrudan Postman’a içe aktarın |
| Insomnia | Doğrudan Insomnia’ya içe aktarın |
| JSON | CI/CD boru hatları, SDK oluşturma |
| YAML | İnsan okunabilir spesifikasyonlar |
Postman koleksiyonunuz her zaman kodunuzla senkronizedir. Manuel bakım yok.
Swagger UI’da API Sürümleme
API_DOCS_VERSIONING=true
Paket, api/v1/*, api/v2/* gibi kalıpları otomatik olarak tespit eder ve Swagger UI’da bir sürüm anahtarı ekler. Her sürüm kendi OpenAPI spesifikasyonuna sahip olur. Ön uç ekibiniz her sürüm için belgeleri tarayabilir.
WebSocket Testi (Evet, Swagger’da)
Swagger UI’den doğrudan WebSocket bağlantılarını test edin. Mesaj gönderin, kanallara abonelik yapın, gerçek zamanlı yanıtları görün — Abone Ol, Abonelikten Çık, Ping ve İstemci Olayları için önceden oluşturulmuş şablonlarla.
Postman yok. wscat yok. Sadece tıklayın ve testi yapın.
Ancak Bekleyin — Ayrıca Tam Bir Yanıt Oluşturucudur
Facade Yöntemi
use Stackmasteraliza\ApiResponse\Facades\ApiResponse;
class UserController extends Controller
{
public function index()
{
$users = User::paginate(15);
return ApiResponse::success($users, 'Kullanıcılar alındı');
}
public function store(StoreUserRequest $request)
{
$user = User::create($request->validated());
return ApiResponse::created($user, 'User created');
}
public function destroy(User $user)
{
$user->delete();
return ApiResponse::noContent();
}
}
Ya Trait Kullanırsanız?
use Stackmasteraliza\ApiResponse\Traits\HasApiResponse;
class UserController extends Controller
{
use HasApiResponse;
public function index()
{
return $this->success(User::paginate(15), 'Kullanıcılar alındı');
}
}
Her ikisi de mükemmel tutarlı yanıtlar sağlar:
{
"status_code": 200,
"success": true,
"message": "Kullanıcılar alındı",
"data": [
{"id": 1, "name": "John Doe"},
{"id": 2, "name": "Jane Doe"}
],
"meta": {
"current_page": 1,
"per_page": 15,
"total": 50,
"last_page": 4,
"from": 1,
"to": 15,
"links": {
"first": "http://example.com/api/users?page=1",
"next": "http://example.com/api/users?page=2"
}
}
}
Paginasyon meta verisi otomatik olarak tespit edilir ve dahil edilir. Ekstra kod yok.
Gerekli Olacak Tüm Hata Yanıtları
ApiResponse::badRequest('Geçersiz giriş'); // 400
ApiResponse::unauthorized('Token süresi dolmuş'); // 401
ApiResponse::forbidden('Sadece yönetici'); // 403
ApiResponse::notFound('Kullanıcı bulunamadı'); // 404
ApiResponse::conflict('E-posta mevcut'); // 409
ApiResponse::validationError($errors); // 422
ApiResponse::tooManyRequests('Yavaşlayın', 60); // 429
ApiResponse::serverError('Bir şeyler bozuldu'); // 500
ApiResponse::serviceUnavailable('Birazdan geri döneceğiz'); // 503
Yapısı her seferinde tutarlıdır:
{
"status_code": 422,
"success": false,
"message": "Doğrulama başarısız",
"errors": {
"email": ["E-posta alanı gereklidir."],
"password": ["Şifre en az 8 karakter olmalıdır."]
}
}
Hata Yönetimi Ki İşlesin
Bunu bootstrap/app.php dosyanıza ekleyin (Laravel 11+):
use Stackmasteraliza\ApiResponse\Exceptions\ApiExceptionHandler;
->withExceptions(function (Exceptions $exceptions) {
$exceptions->render(function (Throwable $e, Request $request) {
return (new ApiExceptionHandler())->handle($e, $request);
});
})
Artık her istisna — ValidationException, ModelNotFoundException, AuthenticationException — temiz, tutarlı bir JSON yanıtı döner. API’nizde HTML hata sayfaları yok.
Test Yardımcıları
Anlamlı API testleri yazın:
$response = $this->getJson('/api/users');
$response->assertApiSuccess()
->assertApiStatusCode(200)
->assertApiMessage('Kullanıcılar alındı')
->assertApiHasData()
->assertApiPaginated();
Her Şeyi Özelleştir
Yapılandırmayı yayınlayın ve kendinize göre yapın:
php artisan vendor:publish --tag=api-response-config
Cevap anahtarlarını, sayfalama anahtarlarını, varsayılan mesajları, tema renklerini, markaları değiştirin — her şey yapılandırılabilir.
// config/api-response.php
'keys' => [
'success' => 'success',
'message' => 'message',
'data' => 'data',
'errors' => 'errors',
'meta' => 'meta',
'status_code' => 'status_code',
],
Özel Makrolarla Genişletin
Özel yanıt türlerine mi ihtiyacınız var? Paket makro oluşturmaya uygundur:
ApiResponse::macro('banned', function (string $reason = 'Hesap askıya alındı') {
return $this->error($reason, 403);
});
// Sonra her yerde kullanın
return ApiResponse::banned('Hesap askıya alındı');
Neden Geliştiriciler Geçiyor?
| Önce | Sonra |
|---|---|
@OA\ notları yazmak için saatler | Koddan otomatik olarak oluşturulan Swagger belgeleri |
| Postman koleksiyonları her zaman güncel değil | Bir tıklama ile Postman/Insomnia dışa aktarma |
| WebSocket belgeleri yok | Swagger’da yerleşik WebSocket testi |
| Tutarsız yanıt formatları | Bir standart JSON yapısı |
| Özel istisna işleyicileri | Yerleşik hata yönetimi |
| Kopyala-yapıştır yanıt kodları | Tek satırlık akıcı yöntemler |
