API Spesifikasyonunuzu Kod Olarak Ele Almak Ne Anlama Gelir?

API sözleşmeniz aynı anda üç yerde yaşıyorsa sorun başlar: wikideki bir diyagram, geçen çeyrek dışa aktarılmış bir Postman koleksiyonu ve iki sürüm önceki servisten kopmuş bir Markdown dosyası. Bu kaynaklar çeliştiğinde ekip tahmin yürütür; tahminler de entegrasyonları bozar.

Apidog'u bugün deneyin

Çözüm: API spesifikasyonunu kod gibi ele almak. Tek bir OpenAPI dosyasını Git’e koyar, PR ile inceler, CI’da doğrular ve sahte sunucu, test, dokümantasyon ve SDK gibi çıktıları bu dosyadan üretirsiniz.

Bu rehberde “spec-as-code” yaklaşımını nasıl uygulayacağınızı, OpenAPI dosyasını neden ana eser yapmanız gerektiğini ve Apidog ile bu akışı nasıl daha yönetilebilir hale getireceğinizi göreceksiniz.

Kod olarak spesifikasyon nedir?

Kod olarak spesifikasyon, API tanımınızın sürüm kontrolünde yaşayan düz metin bir dosya olmasıdır.

Yani:

• Bir veritabanı kaydı değil
• Sadece paylaşım bağlantısı olan barındırılmış bir doküman değil
• Dışa aktarılıp unutulan bir koleksiyon değil

Bunun yerine git diff, branch, merge, review ve revert yapabileceğiniz bir dosyadır.

Bu yaklaşım, docs-as-code fikrinin API sözleşmesine uygulanmış halidir. OpenAPI belgesi, yani YAML veya JSON dosyası, ana eserdir. Diğer tüm çıktılar bu dosyadan türetilir.

Pratikte şu anlama gelir:

• Geliştirici /users/{id} yanıtını öğrenmek için eski wiki sayfasına değil, OpenAPI dosyasına bakar.
• QA ekibi testlerini spesifikasyona göre doğrular.
• Partner ekipler, spesifikasyondan üretilen SDK veya dokümantasyonla entegre olur.
• API değişiklikleri PR üzerinden incelenir.

Tek dosya, birden çok çıktı.

Spesifikasyonu neden kod gibi ele almalıyız?

OpenAPI dosyanız Git’e girdiğinde, kaynak kod için kullandığınız mühendislik pratiklerini API sözleşmesine de uygularsınız.

1. API değişikliklerini PR’da inceleyin

Bir endpoint değiştiğinde fark doğrudan PR’da görünür:

• Yeni alan eklendi mi?
• Status code değişti mi?
• Response schema geriye dönük uyumluluğu bozuyor mu?
• Zorunlu alan kaldırıldı mı?
• Enum değerleri değişti mi?

Bozucu değişiklik artık production’da sürpriz olmaz. Merge öncesinde review konusu olur.

Bu yaklaşım, Git-tabanlı bir API iş akışının temelidir.

2. Diff okunabilir hale gelir

YAML veya JSON düz metindir. Bu yüzden küçük bir schema değişikliğini saniyeler içinde okuyabilirsiniz.

Örneğin:

 status:
   type: string
-  enum: [beklemede, gönderildi]
+  enum: [beklemede, gönderildi, teslim edildi]

Bu fark, barındırılan bir araçtaki görünmez değişiklik geçmişinden çok daha nettir.

3. API geçmişi denetlenebilir olur

Git sayesinde her değişiklik şunlara sahip olur:

• Commit
• Yazar
• Zaman damgası
• Branch
• Tag
• Geri alma imkanı

Bir v2 tasarımı için branch açabilir, belirli bir API sürümünü tag’leyebilir veya hatalı bir değişikliği git revert ile geri alabilirsiniz.

Dallanma ve etiketleme stratejileri için Git ile OpenAPI sürüm kontrolü yazısına bakabilirsiniz.

4. Tek doğruluk kaynağı oluşur

Sahte sunucu, testler, dokümantasyon ve SDK’lar aynı OpenAPI dosyasından üretildiğinde birbirinden kopmaz.

Spesifikasyonu güncellersiniz, çıktıları yeniden üretirsiniz ve tüm sistem aynı sözleşmeye göre çalışır.

Endişe	Barındırılan araçta spesifikasyon	Kod olarak API spesifikasyonu
Değişiklik incelemesi	Manuel, kaçırması kolay	PR diff’i ve review
Geçmiş	Sınırlı veya satıcıya bağımlı	Tam Git geçmişi
Geri alma	Genellikle manuel	git revert
Doğruluk kaynağı	Belirsiz	Commit’lenmiş dosya
CI entegrasyonu	Eklentiye bağlı	Doğal

OpenAPI’yi ana eser yapın

OpenAPI, API sözleşmesini kod olarak tutmak için en yaygın formatlardan biridir. Makine tarafından okunabilir, insan tarafından incelenebilir ve geniş araç desteğine sahiptir.

Aşağıdaki örnek, deponuzda api/openapi.yaml gibi bir konumda tutulabilecek küçük bir OpenAPI 3.1 dosyasıdır:

openapi: 3.1.0
info:
  title: Siparişler API'si
  version: 1.2.0

paths:
  /orders/{orderId}:
    get:
      summary: Kimliğe göre bir sipariş al
      operationId: siparisAl
      parameters:
        - name: orderId
          in: path
          required: true
          schema:
            type: string
            format: uuid
      responses:
        "200":
          description: İstenen sipariş
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Order"
        "404":
          description: Sipariş bulunamadı

components:
  schemas:
    Order:
      type: object
      required:
        - id
        - status
        - total
      properties:
        id:
          type: string
          format: uuid
        status:
          type: string
          enum:
            - beklemede
            - gönderildi
            - teslim edildi
        total:
          type: number
          format: float

Bu dosya sözleşmedir.

Örneğin:

• Order şemasına alan eklerseniz PR’da görünür.
• status enum değerini değiştirirseniz reviewer bunu fark eder.
• Yeni endpoint eklerseniz test, mock ve dokümantasyon aynı kaynaktan güncellenir.

Basit bir repo yapısı şöyle olabilir:

my-service/
├── api/
│   └── openapi.yaml
├── src/
├── tests/
└── package.json

API sözleşmesi, tanımladığı servis kodunun yanında yaşar.

Spesifikasyondan ne üretmelisiniz?

Tek OpenAPI dosyasının asıl değeri, ondan üretilen çıktılardır.

Sahte sunucular

Bir mock server’ı OpenAPI dosyasına bağlayarak backend hazır olmadan çalıştırılabilir bir API elde edebilirsiniz.

Bu özellikle şu ekipler için faydalıdır:

• Frontend
• Mobil
• QA
• Partner entegrasyon ekipleri

Sözleşme değiştiğinde mock API de aynı dosyadan güncellenir.

Sözleşme testleri

Canlı servisin OpenAPI spesifikasyonuyla eşleştiğini doğrulayan testler ekleyin.

Örneğin testler şunları yakalayabilir:

• Spesifikasyonda olmayan alan döndürülmesi
• Belgelenmiş alanın response’tan kaldırılması
• Yanlış status code dönülmesi
• Zorunlu alanın eksik olması
• Response tipinin değişmesi

Bu kontroller CI’da çalıştığında, sözleşmeden sapma müşteriye ulaşmadan yakalanır.

Dokümantasyon

OpenAPI dosyasını referans dokümantasyonuna dönüştürün.

Böylece:

• Endpoint tabloları elle yazılmaz.
• Parametreler spesifikasyondan gelir.
• Request ve response örnekleri sözleşmeyle uyumlu kalır.
• Dokümantasyon, API değişikliğiyle birlikte güncellenir.

SDK’lar

Aynı OpenAPI dosyasından farklı diller için client SDK üretebilirsiniz.

Örneğin:

• TypeScript
• Java
• Python
• Go
• Kotlin
• Swift

Böylece tüketici ekipler elle request yazmak yerine tip güvenli istemcilerle çalışabilir.

Kural basit: Girdi OpenAPI dosyasıdır. Çıktılar bu dosyanın fonksiyonudur.

Apidog spesifikasyonu nasıl doğruluk kaynağı haline getirir?

Kod olarak spesifikasyonu elle kurmak mümkündür; ancak genellikle birden fazla aracı birleştirmeniz gerekir:

• OpenAPI editörü
• Linter
• Mock server
• Dokümantasyon aracı
• Test aracı
• Git senkronizasyonu
• CI entegrasyonu

Apidog bu parçaları tek bir iş akışında birleştirir.

Apidog’un Spec-First Modu, OpenAPI dosyanızı yetkili tanım olarak ele alır. Endpoint’leri spesifikasyona göre tasarlarsınız; Apidog da mock server, test ve dokümantasyon çıktılarınızı bu sözleşmeyle senkronize tutar.

En kritik parça çift yönlü Git senkronizasyonudur.

Bu sayede:

• OpenAPI dosyası Git deposundan okunabilir.
• Apidog’daki değişiklikler tekrar Git’e yazılabilir.
• Görsel tasarım yapan ekip üyeleri ile YAML düzenleyen ekip üyeleri aynı sözleşmede buluşur.
• PR review akışı korunur.
• OpenAPI dosyası tek doğruluk kaynağı olmaya devam eder.

Daha hızlı olduğunda görsel arayüzde tasarlayın. Daha hızlı olduğunda YAML dosyasını doğrudan düzenleyin. Her iki yol da aynı commit’lenmiş dosyaya iner.

GitHub senkronizasyon detayları için OpenAPI spesifikasyonunuzu GitHub ile nasıl senkronize edeceğinize bakabilirsiniz.

Sonuç: Görsel araçlar OpenAPI dosyasının yerine geçmez; onun üzerinde çalışır.

Yaygın tuzaklar

Kod olarak spesifikasyon basit görünür, ancak birkaç hata ekibin erken aşamada takılmasına neden olabilir.

1. Spesifikasyon ile uygulamanın sapması

OpenAPI dosyasını yazmak yeterli değildir. Çalışan servis bu dosyayla karşılaştırılmıyorsa zamanla ayrışır.

Çözüm:

• CI’a sözleşme testleri ekleyin.
• Response schema doğrulaması yapın.
• Status code ve content type kontrollerini otomatikleştirin.
• Spesifikasyona uymayan deploy’u engelleyin.

2. Üretilmiş ve elle yazılmış kaynakları karıştırmak

Spesifikasyonun kaynağı net olmalıdır.

İki yaygın model vardır:

1. Spesifikasyon elle yazılır ve kod ona uyar.
2. Spesifikasyon kod açıklamalarından üretilir.

İkisini aynı anda ana kaynak gibi kullanırsanız, kimse hangi tarafın yetkili olduğunu bilemez.

Bir yön seçin. Eğer OpenAPI dosyası doğruluk kaynağıysa, kod açıklamalarını ikinci bir ana kopya olarak değil, doğrulanacak uygulama detayı olarak ele alın.

3. Spesifikasyonu sadece dokümantasyon sanmak

Sadece okunan spesifikasyon dokümandır.

Şunları üreten spesifikasyon ise sözleşmedir:

• Mock server
• Test
• Dokümantasyon
• SDK

Değer, dosyanın varlığından değil, bu dosyanın iş akışına bağlanmasından gelir.

4. Review sürecini atlamak

Git’te duran ama review edilmeyen bir OpenAPI dosyası yeterli değildir.

Spesifikasyon değişiklikleri için de kod gibi review isteyin:

• Endpoint adı doğru mu?
• Response modeli uyumlu mu?
• Breaking change var mı?
• Error response’lar belgelenmiş mi?
• Alan adları tutarlı mı?

PR, API tasarım kararlarının tartışıldığı yer olmalıdır.

Başlamak için uygulanabilir plan

Kod olarak spesifikasyonu kademeli şekilde benimseyebilirsiniz.

1. OpenAPI dosyasını depoya ekleyin

Önerilen konum:

api/openapi.yaml

Dosyayı servis koduyla aynı repoda tutun. Böylece API değişikliği ile uygulama değişikliği aynı PR’da incelenebilir.

2. PR review zorunlu hale getirin

Spesifikasyon değişikliklerinin doğrudan merge edilmesini engelleyin.

Örneğin branch protection ile:

• En az bir reviewer isteyin.
• CI kontrolü geçmeden merge’i engelleyin.
• Breaking change içeren PR’ları ayrıca işaretleyin.

3. Bir çıktı üretin

Başlangıçta her şeyi otomatikleştirmek zorunda değilsiniz.

İlk çıktı olarak şunlardan birini seçin:

• Mock server
• Dokümantasyon
• SDK
• Contract test

Bir çıktı bile OpenAPI dosyasını aktif bir sözleşmeye dönüştürmeye başlar.

4. CI’da OpenAPI lint çalıştırın

Her PR’da spesifikasyonun geçerli olduğundan emin olun.

Kontrol edilecek şeyler:

• Geçerli OpenAPI syntax
• Eksik operationId
• Eksik response description
• Tutarsız schema adları
• Belgelenmemiş error response’lar

Amaç, geçersiz sözleşmenin merge edilmesini engellemektir.

5. Sözleşme testleriyle döngüyü kapatın

Son adımda canlı servisi spesifikasyona göre doğrulayın.

Bu noktada akış şöyle olur:

1. OpenAPI dosyası değişir.
2. PR’da incelenir.
3. CI’da lint edilir.
4. Mock, dokümantasyon veya SDK güncellenir.
5. Canlı servis sözleşmeye göre test edilir.

Bu döngü kurulduğunda OpenAPI dosyası gerçekten tek doğruluk kaynağı haline gelir.

Sonuç

Kod olarak spesifikasyon küçük bir değişiklik gibi görünür: OpenAPI dosyasını Git’e koymak.

Ama etkisi büyüktür:

• API değişiklikleri review edilebilir olur.
• Geçmiş ve geri alma Git üzerinden yönetilir.
• Mock server, test, dokümantasyon ve SDK aynı kaynaktan üretilir.
• Spesifikasyon ile uygulama arasındaki sapma CI’da yakalanır.
• API sözleşmesi ekipler arasında netleşir.

Görsel düzenleme, mock, test, dokümantasyon ve Git senkronizasyonunun aynı akışta olmasını istiyorsanız Apidog’un Spec-First Modunu deneyin ve OpenAPI dosyanızın tek doğruluk kaynağı olarak kalmasını sağlayın.

SSS

“API spesifikasyonu kod olarak” ile “belgeler kod olarak” aynı şey midir?

Hayır, ama aynı felsefeyi paylaşırlar.

Docs-as-code, dokümantasyonu sürüm kontrolünde tutar ve normal geliştirme işlem hattından geçirir. Spec-as-code ise aynı yaklaşımı API sözleşmesine uygular.

Pratikte birbirlerini güçlendirirler. Çünkü commit’lenmiş OpenAPI dosyasından üretilen dokümantasyon zaten kod olarak belge yaklaşımına uygundur.

Spesifikasyon dosyası hangi formatı kullanmalı?

YAML formatında OpenAPI yaygın bir tercihtir.

YAML:

• İnsan tarafından okunabilir.
• PR diff’lerinde temiz görünür.
• Mock, test, dokümantasyon ve SDK araçları tarafından ayrıştırılabilir.

JSON da kullanılabilir; ancak YAML genellikle review sürecinde daha okunaklıdır.

Spesifikasyonun gerçek API’den sapmasını nasıl önleyebilirim?

CI’a sözleşme testleri ekleyin.

Bu testler çalışan servisin commit’lenmiş OpenAPI dosyasıyla eşleştiğini doğrulamalıdır. Eğer endpoint belgelenmemiş alan döndürürse, zorunlu alanı çıkarırsa veya yanlış status code dönerse build başarısız olmalıdır.

Bu geri bildirim döngüsü, spesifikasyonu sadece okunacak bir belge olmaktan çıkarıp uygulanabilir bir API sözleşmesine dönüştürür.