Laravel İle Dinamik Bir Apı Dokümantasyon Sistemi Nasıl Yapılır?

Gereksinimler ve Ön Hazırlık

Başarılı bir kurulum için bilgisayarınızda PHP 8.3 veya üzeri bir sürümün, Composer paket yöneticisinin ve güncel bir Laravel 11+ projesinin kurulu olması gerekmektedir. Ayrıca, API uç noktalarınızı test edebilmek için Postman veya Insomnia gibi bir araç bulundurmanız önerilir.

• PHP 8.3+
• Laravel 11.x
• Composer 2.x
• Tercihen bir veritabanı (MySQL veya PostgreSQL)

Kurulum öncesinde projenizin bağımlılıklarının güncel olduğundan emin olun. Terminalinizi açın ve projenizin kök dizininde composer update komutunu çalıştırarak tüm paketlerin en son kararlı sürümlerini çektiğinizden emin olun.

Adım 1: Dokümantasyon Paketinin Kurulumu

Laravel projelerinde dokümantasyon için en yaygın ve dinamik yöntem OpenApi (eski adıyla Swagger) standartlarını kullanmaktır. darkaonline/l5-swagger paketi, Laravel rotalarınızı ve controller sınıflarınızı tarayarak dokümantasyonu otomatik oluşturur.

composer require "darkaonline/l5-swagger"

Paketi kurduktan sonra, konfigürasyon dosyalarını projenize yayınlamanız gerekir. Bu dosya, dokümantasyonun nasıl görüneceğini ve hangi rotaların taranacağını belirler.

php artisan vendor:publish --provider "L5Swagger\L5SwaggerServiceProvider"

Adım 2: API Bilgilerinin Yapılandırılması

Dokümantasyonunuzun ana giriş noktasını belirlemek için app/Http/Controllers/Controller.php dosyasına veya ayrı bir OpenApi tanım dosyasına temel bilgileri eklemelisiniz. Bu bilgiler, dokümantasyon sayfanızın en üstünde yer alacaktır.

/**
 * @OA\Info(
 *     version="1.0.0",
 *     title="Proje API Dokümantasyonu",
 *     description="Laravel 11 ile geliştirilen dinamik API sistemi."
 * )
 */
class Controller extends BaseController { ... }

Bu blok, Swagger'ın projenizi tanıması için gerekli olan temel meta verileri içerir. version, title ve description alanları, API'nizin kimliğini oluşturur.

Adım 3: Controller Uç Noktalarını Dokümante Etme

Dinamik yapının en güçlü yanı, kodun içine gömülü olan açıklamalardır. Bir controller metodunun üzerine ekleyeceğiniz @OA\Get veya @OA\Post etiketleri, sistemin otomatik olarak rotayı algılamasını sağlar.

/**
 * @OA\Get(
 *     path="/api/kullanicilar",
 *     summary="Kullanıcı listesini getirir",
 *     @OA\Response(response="200", description="Başarılı işlem")
 * )
 */
public function index() {
    return User::all();
}

Bu kod bloğu, /api/kullanicilar rotasını tarar ve bunu dokümantasyon sayfasına bir GET metodu olarak ekler. @OA\Response etiketi ile dönen verinin yapısını da tanımlayabilirsiniz.

Adım 4: Dokümantasyonun Üretilmesi ve Test Edilmesi

Kodlarınızı tanımladıktan sonra, Swagger'ın bu kodları tarayıp statik bir JSON dosyasına dönüştürmesi gerekir. Bu işlem, her kod değişikliğinden sonra dokümantasyonun güncellenmesini sağlar.

php artisan l5-swagger:generate

Bu komut çalıştırıldıktan sonra, projenizin storage/api-docs klasöründe api-docs.json dosyası oluşturulacaktır. Artık tarayıcınızdan /api/documentation rotasına giderek dinamik dokümantasyonunuzu görüntüleyebilirsiniz.

Güvenlik Uyarısı: Üretim (production) ortamında dokümantasyon sayfasına erişimi kısıtlamayı unutmayın. config/l5-swagger.php dosyasındaki generate_always ayarını üretimde false yaparak performans kaybını önleyebilir ve dokümantasyonun yetkisiz kişilerin erişimine kapalı olduğundan emin olabilirsiniz.

Adım 5: Karşılaştırmalı API Dokümantasyon Yöntemleri

API dokümantasyonu için farklı yaklaşımlar mevcuttur. İhtiyacınıza en uygun olanı seçmek için aşağıdaki tabloyu inceleyebilirsiniz.

Adım 6: Hata Ayıklama ve İpuçları

Dokümantasyon sayfasına girdiğinizde "404 Not Found" hatası alıyorsanız, rotalarınızın api.php içerisinde doğru tanımlandığından emin olun. Ayrıca, .env dosyanızdaki APP_URL değerinin doğru ayarlandığını kontrol edin. Swagger, bazen yanlış URL yapılandırmaları nedeniyle istekleri doğru adrese yönlendiremeyebilir.

// .env dosyanızda kontrol edin
APP_URL=http://localhost:8000

Eğer dokümantasyon sayfanızda değişiklikler görünmüyorsa, önbelleği temizleyerek yeniden oluşturmayı deneyin:

php artisan config:clear
php artisan l5-swagger:generate

Sorumluluk Reddi: Bu rehberde paylaşılan kod örnekleri eğitim amaçlıdır. Uygulamanızda kullanacağınız veritabanı işlemlerinde her zaman Laravel'in sunduğu Eloquent ORM veya Query Builder'ı kullanarak SQL Injection saldırılarına karşı koruma sağlayın. Şifreleme gerektiren verilerde Hash::make() fonksiyonunu kullanmayı ihmal etmeyin.

Sıkça Sorulan Sorular

Swagger dokümantasyonunu sadece belirli rotalar için nasıl kısıtlarım?

config/l5-swagger.php dosyasındaki paths bölümünü düzenleyerek sadece belirli dizinlerin taranmasını sağlayabilirsiniz.

Dokümantasyon sayfasına nasıl şifre koruması eklerim?

app/Providers/AuthServiceProvider.php içerisinde Gate::define('viewApiDocs', ...) kullanarak rotaya erişimi yetkilendirebilirsiniz.

Dinamik dokümantasyon performans düşürür mü?

generate_always seçeneği true olduğunda her istekte tarama yapılır. Üretim ortamında bu ayarı false yapmalısınız.

Farklı API sürümleri için ayrı dokümantasyon oluşturabilir miyim?

Evet, l5-swagger konfigürasyonunda birden fazla "api" tanımı oluşturarak farklı sürümleri (v1, v2) ayrı sayfalarda sunabilirsiniz.

Özel veri tiplerini (DTO) nasıl dokümante ederim?

@OA\Schema etiketlerini kullanarak sınıflarınızı tanımlayabilir ve bunları @OA\Property ile detaylandırabilirsiniz.

API Dokümantasyonunu CI/CD Süreçlerine Entegre Etme

Dinamik dokümantasyonun en büyük avantajı, kod tabanı değiştikçe dokümanın da güncellenebilmesidir. Ancak bu süreci manuel tetiklemek yerine, CI/CD (Sürekli Entegrasyon ve Sürekli Dağıtım) hattınıza dahil ederek her deployment aşamasında dokümantasyonun otomatik olarak yeniden oluşturulmasını sağlayabilirsiniz. Bu sayede, canlı ortamdaki API referansınız her zaman en son kod değişikliğini yansıtır.

GitHub Actions kullanarak, her "push" işleminde dokümantasyon dosyasını (JSON/YAML) güncelleyen basit bir iş akışı şu şekilde yapılandırılabilir:

name: Generate API Documentation
on: [push]
jobs:
  docs:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v2
      - name: Install Dependencies
        run: composer install
      - name: Generate Swagger JSON
        run: php artisan l5-swagger:generate
      - name: Deploy Docs
        run: |
          # Doküman dosyasını sunucuya taşıma veya statik siteye aktarma komutları
          scp storage/api-docs/api-docs.json user@your-server:/var/www/html/docs/

İleri Seviye: OpenAPI Şemalarını Paylaşılan Bir Kütüphaneye Taşıma

Büyük ölçekli mikroservis mimarilerinde, birden fazla Laravel projesi aynı veri modellerini (örneğin; User veya Product DTO'ları) kullanıyor olabilir. Her serviste aynı @OA\Schema tanımlarını tekrarlamak yerine, bu şemaları bağımsız bir PHP paketi içinde toplayabilirsiniz.

Bu yaklaşım, dokümantasyonun tutarlılığını sağlar ve "Single Source of Truth" (Tek Doğruluk Kaynağı) prensibini destekler. Şemalarınızı bir Trait veya Base Class içerisinde tanımlayarak projenize dahil edebilirsiniz:

namespace App\Docs\Schemas;

/**
 * @OA\Schema(
 *     schema="UserResponse",
 *     type="object",
 *     @OA\Property(property="id", type="integer", example=1),
 *     @OA\Property(property="email", type="string", example="test@example.com")
 * )
 */
class UserSchema {
    // Paylaşılan şema tanımları
}

Ardından, Controller içerisinde bu şemayı doğrudan referans göstererek dokümantasyonunuzu temiz tutabilirsiniz:

/**
 * @OA\Get(
 *     path="/api/user",
 *     @OA\Response(
 *         response=200,
 *         description="Başarılı",
 *         @OA\JsonContent(ref="#/components/schemas/UserResponse")
 *     )
 * )
 */
public function show() { ... }

Dokümantasyon Kalitesini Artıran İpuçları

• Örnek Veri (Examples): example="değer" parametresini kullanmak, API tüketicilerinin verinin formatını anlamasını %50 oranında hızlandırır.
• Hata Kodları: Sadece başarılı yanıtları değil, 401, 403 ve 422 gibi yaygın hata yanıtlarını da şema olarak ekleyin.
• Güvenlik Tanımları: API'niz JWT veya Sanctum kullanıyorsa, @OA\SecurityScheme etiketlerini kullanarak Swagger arayüzünde "Authorize" butonunun aktif olmasını sağlayın.

Bu ileri seviye yapılandırmalar, dokümantasyonunuzu sadece bir referans sayfası olmaktan çıkarıp, yazılım geliştirme yaşam döngünüzün ayrılmaz bir parçası haline getirir.

Sonuç

Laravel ile dinamik bir API dokümantasyon sistemi kurmak, projenizin profesyonellik seviyesini artırırken, diğer geliştiricilerle olan iş birliğinizi kolaylaştırır. Bu rehberde öğrendiğiniz yöntemleri projenize entegre ederek, manuel dokümantasyonun getirdiği hatalardan kurtulabilir ve her zaman güncel bir API referansına sahip olabilirsiniz. Bir sonraki adım olarak, dokümantasyonunuza "Örnek İstek" (Example Request) ve "Örnek Yanıt" (Example Response) alanlarını ekleyerek API kullanımını daha da basitleştirebilirsiniz.