API'leri OpenAPI ile belgelemek

Bir API geliştirdiğinizde, belgeleme çoğu zaman sonraya bırakılan bir iş gibi görünür. Önce çalışır hale getir, sonra yazar; ama o “sonra” ya hiç gelmez ya da geldiğinde kod çoktan değişmiş olur. API belgesi ile gerçek davranış arasındaki makas açıldıkça, istemci ekipleri için güvenilir tek doğru kaynak ortadan kalkar.

OpenAPI (eski adıyla Swagger), bu soruna doğrudan yanıt verir: API’yi makine okunabilir bir sözleşme olarak tanımlamak. Belgeyi koddan sonra yazmak yerine, ya koddan türetmek ya da önce sözleşme yazıp kodla takip etmek. İkisi de geçerli yaklaşım; hangisini seçtiğiniz ekip büyüklüğüne ve projenin olgunluğuna göre değişir.

Neden OpenAPI

OpenAPI’nin gerçek değeri, bir YAML ya da JSON dosyasının çok ötesine geçer. Spesifikasyon hazır olduğunda istemci kodu üretebilir, test senaryoları yazabilir, mock sunucu ayağa kaldırabilirsiniz. Frontend ekibi API’niz henüz implement edilmeden önce gerçek davranışı taklit eden bir sunucuya karşı geliştirmeye başlayabilir.

PHP ile Laravel kullandığınızda bu süreç için birkaç olgun araç var. Ben son dönemde dedoc/scramble paketini tercih ediyorum. Route’ları, form request sınıflarını ve API resource sınıflarını okuyarak spesifikasyonu otomatik üretiyor.

composer require dedoc/scramble

Yükledikten sonra /docs/api adresinde canlı belgeler hemen erişilebilir hale geliyor. Başka bir yapılandırma gerekmez.

Spesifikasyonun anatomisi

Bir OpenAPI belgesi üç temel katmandan oluşur: info (API adı ve sürüm), paths (uç noktalar ve HTTP metotları) ve components (yeniden kullanılan şema tanımları).

openapi: "3.1.0"
info:
  title: "Örnek API"
  version: "1.0.0"
paths:
  /users/{id}:
    get:
      summary: "Kullanıcıyı getir"
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: integer
      responses:
        "200":
          description: "Başarılı"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/User"
components:
  schemas:
    User:
      type: object
      properties:
        id:
          type: integer
        name:
          type: string
        email:
          type: string

$ref mekanizması burada kritik. Aynı şemayı birden çok uç noktada tekrar tekrar tanımlamak yerine merkezi tanımlar oluşturuyorsunuz. Şema değiştiğinde tek yerde güncelliyorsunuz.

Koddan türetmek vs. sözleşme öncelikli

Koddan türetme (code-first) yaklaşımı, var olan bir API’yi belgelemek için hızlıdır. Özellikle ekip küçükse ve tüm taraflar aynı repo içindeyse, otomatik üretilen belge yeterli olur. Scramble gibi araçlar bunu büyük ölçüde otomatikleştirir.

Sözleşme öncelikli (contract-first) yaklaşım ise farklı ekiplerin paralel çalışması gerektiğinde değerini gösterir. Önce OpenAPI dosyasını yazıyorsunuz, sonra hem backend hem frontend bu sözleşmeye göre ilerlemeye başlıyor. Entegrasyon anında sürpriz olmuyor; her iki taraf da bağımsız olarak ilerleyebiliyor.

Ben bireysel projelerde kod-öncelikli, ekip projelerinde sözleşme-öncelikli çalışıyorum. Bu ikisi arasında evrensel bir doğru yok; asıl mesele hangisini seçtiğinizi ekip içinde herkesle netleştirmek.

Sürümleme ve değişiklik yönetimi

API sözleşmesi bir kez yayınlandıktan sonra kırıcı değişiklik (breaking change) yapmak istemcileri etkiler. OpenAPI belgesi bu noktada da yardımcı olur: iki sürüm arasındaki farkı araçlarla karşılaştırabilir, neyin kırıcı olduğunu otomatik tespit edebilirsiniz. oasdiff gibi araçlar bu karşılaştırmayı doğrudan CI süreçlerine ekleyebilir.

Pratikte ne zaman yeni sürüm çıkaracağınıza, ne zaman mevcut sözleşmeyi genişleteceğinize belirli bir kural koymak gerekiyor. Genişletme (yeni alan eklemek, yeni uç nokta eklemek) genellikle güvenli; çıkarmak veya tip değiştirmek ise her zaman sürüm atlama gerektiriyor.

Belgeyi canlı tutmak

Otomatik üretim bir yere kadar yardımcı olur. Açıklama metinleri, örnek değerler, hata yanıtlarının detayı — bunlar hâlâ elle yazılması gereken içerik. Kodun doğru çalışmasını sağlarken belgenin de eksiksiz kalmasını sağlamak bir disiplin meselesi.

Ben bunu kod incelemesi sırasında kural haline getirdim: yeni bir uç nokta eklendiyse ya da mevcut biri değiştiyse, PR açıklamasında belgenin ne yönde güncelleneceğini not olarak bırakmak. Küçük bir sürtünme gibi görünse de, birkaç ay sonra anlaşılmaz bir belgeyle uğraşmak yerine bu küçük adım çok daha az maliyetli.

API belgesi, geriye dönük baktığınızda her zaman “keşke baştan yapsaydık” dediğiniz bir şeydir. OpenAPI bu işi mümkün olduğunca erken ve az maliyetle başlatmak için yeterince olgunlaşmış bir araç.