Git ile OpenAPI Spesifikasyonunu Nasıl Sürüm Kontrol Edersiniz?

OpenAPI belirtiminiz bir sözleşmedir. Bu sözleşme değiştiğinde, istemciler bozulur, sahte veriler eskimiş hale gelir ve testler artık var olmayan bir API'ye karşı başarılı olur. Bu nedenle belirtimi kodunuzun geri kalanı gibi ele alın: Git'e koyun, dallandırın, inceleyin ve her değişiklikte doğrulayın.

Bu rehber, Git ile OpenAPI sürüm kontrolünü en temelden anlatır. Dosyanın nerede bulunduğunu, nasıl dallandırılacağını, inceleyicilerin bir belirtim farkında ne aradığını ve değişikliklerin doğrudan Apidog'dan nasıl gönderileceğini gösterir. Sonunda tüm ekibinizin güvenebileceği bir iş akışına sahip olacaksınız.

OpenAPI Belirtiminiz için Neden Sürüm Kontrolü Kullanmalısınız?

Bir wiki'de veya paylaşılan bir sürücüde duran bir belirtimin geçmişi yoktur. Geçen Salı POST /orders yükünü kimin değiştirdiğini veya neden değiştirdiğini göremezsiniz. Git bunu düzeltir.

openapi.yaml dosyasını sürüm kontrolü altına aldığınızda dört şeyi ücretsiz olarak elde edersiniz:

• Geçmiş. Her değişiklik bir yazar, bir zaman damgası ve bir mesaj içeren bir commit'tir.
• Suçlama. git blame openapi.yaml, o gerekli alanı kimin ve ne zaman eklediğini size söyler.
• Geri alma. Sözleşmeyi bozan kötü bir birleştirme mi oldu? Commit'i geri alın ve çalışan bir belirtime geri dönün.
• İnceleme. Belirtim değişiklikleri çekme istekleri (pull request) aracılığıyla yapılır, böylece ikinci bir kişi dağıtımdan önce farkı görür.

Bu, Git-tabanlı bir API iş akışının temelidir: belirtim bir kaynak kodudur ve kaynak kod Git'te yaşar.

Belirtim Dosyası Repo'da Nerede Bulunur?

Basit ve öngörülebilir tutun. Çoğu ekip tek bir openapi.yaml dosyasını depo köküne veya bir api/ klasörüne koyar:

my-service/
├── api/
│ └── openapi.yaml
├── src/
└── README.md

Birden çok ana sürümü paralel olarak sürdürdüğünüzde, her ana sürüm için bir dosya olacak şekilde sürüme göre ayırın:

api/
├── api-v1.yaml
└── api-v2.yaml

Bu, bozan değişiklikleri izole tutar. api-v1.yaml mevcut istemciler için donmuş kalırken, api-v2.yaml gelişir. Ayrıca, her dosya tek bir nedenle değiştiği için farkları küçültür ve incelemeyi hızlandırır. Belirtimi bu şekilde ele almak, kod olarak API belirtimi kavramının temel fikridir.

Bir kural seçin ve bunu belgeleyin. En kötü sonuç, iki dosyanın "ana" belirtim olduğunu iddia etmesidir.

Belirtim Değişiklikleri için Dallandırma Stratejileri

Belirtimler için özel bir dallandırma modeline ihtiyacınız yok. Kodunuzun zaten kullandığı şeyi yeniden kullanın. main'den dallandırın, değişikliği yapın, bir çekme isteği (PR) açın.

belirtim dallarını taramayı kolaylaştıran adlandırma kuralı:

api/ öneki, "bu PR sözleşmeye dokunuyor" mesajını bir bakışta verir. İnceleyiciler ve CI buna göre filtreleyebilir. Bozan değişiklikler için, açık breaking- öneki, bunun ek gözlere ve muhtemelen bir sürüm artışına ihtiyacı olduğunun bir işaretidir.

Dalları kısa ömürlü tutun. İki hafta yaşayan bir belirtim dalı, diğer herkesin değişiklikleriyle çakışacaktır. Küçük, odaklanmış dallar sorunsuz bir şekilde birleşir.

Çekme İsteğinde Belirtim Değişikliklerini İnceleme

İşte sürüm kontrolünün değerini gösterdiği yer burasıdır. Bir belirtim PR'ı bir sözleşme değişikliğidir ve sözleşme değişiklikleri gerçek bir incelemeyi hak eder.

İnceleyicilerin biçimlendirmeyle boğuşmak yerine değişikliği okuyabilmesi için YAML'ı fark dostu bir şekilde yazın:

paths:
 /orders/{orderId}:
 get:
 summary: Get an order
 parameters:
 - name: orderId
 in: path
 required: true
 schema:
 type: string
 responses:
 "200":
 description: Order found
 content:
 application/json:
 schema:
 $ref: "#/components/schemas/Order"

Tutarlı girintileme ve satır başına tek bir özellik, tek bir alan eklemesinin tek satırlık bir fark olarak görünmesini sağlar. Amaç budur.

İnceleyicilerin kontrol etmesi gerekenler:

• Bozan değişiklikler. Bir isteğe gerekli bir alan eklendi mi? Bir yanıt alanı kaldırıldı veya yeniden adlandırıldı mı? Bir enum değeri kaybetti mi? Her biri mevcut istemcileri bozabilir.
• Geriye dönük uyumluluk. Yeni isteğe bağlı alanlar ve yeni uç noktalar güvenlidir. Mevcut şekillerdeki değişiklikler ise güvenli değildir.
• Adlandırma ve tutarlılık. Yeni uç nokta, API'nin geri kalanının büyük/küçük harf kullanımına ve çoğullaştırılmasına uygun mu?
• Tamamlanmışlık. Her yeni işlem bir summary, yanıt şemaları ve hata yanıtları gerektirir.
• Örnekler. Gerçekçi örnekler, belgeleri ve sahte verileri kullanışlı hale getirir.

Bozan değişiklik tespiti için gözle kontrol yerine araçlara güvenin. Bir CI adımı (aşağıda ele alınmıştır), PR'ın belirtimini main ile karşılaştırabilir ve uyumsuz bir değişiklik tespit ederse derlemeyi başarısız edebilir. İnsanlar bunları gözden kaçırır; fark araçları kaçırmaz.

Apidog'dan Commit ve Push Yapma

Ham YAML'ı elle düzenlemek işe yarar, ancak canlı doğrulama özelliğine sahip görsel bir düzenleyici daha hızlıdır ve hataları daha erken yakalar. Apidog'un Spec-First Modu size iki yönlü Git senkronizasyonu sağlar: belirtimi kullanıcı arayüzünde düzenleyin, commit yapın ve aracı terk etmeden deponuza push yapın. Bir ekip arkadaşınızın değişikliklerini aynı şekilde geri çekin.

İş akışı şöyle görünür:

1. Git deponuzu bağlayın ve Apidog'u belirtim dosyasına yönlendirin.
2. Uç noktaları, şemaları ve örnekleri görsel düzenleyicide düzenleyin.
3. Apidog, temiz, fark dostu YAML'ı dosyaya geri yazar.
4. Bir daldan commit yapın ve push edin, ardından PR'ınızı her zamanki gibi açın.

Apidog YAML'ı tutarlı bir şekilde seri hale getirdiği için, farklarınız küçük ve incelenebilir kalır, gürültülü yeniden sıralama veya yeniden biçimlendirme olmaz. Tam kurulumu Apidog Spec-First Modu belgelerinde okuyabilirsiniz. Dosyanın belirli bir sağlayıcıya düşmesini istiyorsanız, OpenAPI belirtiminizi GitHub ile senkronize etmeye bakın.

CI Doğrulama Kancaları

Asla geçersiz bir belirtimin main'e ulaşmasına izin vermeyin. Doğrulamayı çekme isteği kontrollerinize entegre edin, böylece bozuk bir sözleşme derlemeyi otomatik olarak başarısız kılar.

Minimum bir GitHub Actions adımı:

name: Validate OpenAPI
on: [pull_request]
jobs:
 lint:
 runs-on: ubuntu-latest
 steps:
 - uses: actions/checkout@v4
 - name: Lint spec
 run: npx @redocly/cli lint api/openapi.yaml

Büyüdükçe daha fazla kontrol ekleyin:

• Yapısal ve stil sorunları için belirtimi lint edin.
• Geçerli bir OpenAPI 3.x olarak ayrıştırıldığını doğrulayın.
• Bozan değişiklikleri tespit etmek ve PR üzerinde işaretlemek için main ile karşılaştırın.

Bu kontroller saniyeler içinde çalışır ve insan bir inceleyicinin gözden kaçıracağı hataları yakalar.

En İyi Uygulamalar

Birkaç alışkanlık, belirtim sürüm kontrolünü zamanla sağlıklı tutar:

• Semantik sürümlemeyi kullanın. info.version alanını artırın. Bozan değişiklik yeni bir ana sürüm anlamına gelir; geriye dönük uyumlu eklemeler küçük sürümü artırır.
• Bir değişiklik günlüğü tutun. Belirtimin yanında kısa bir CHANGELOG.md, tüketicilere sürümler arasında nelerin değiştiğini söyler.
• Küçük farklar gönderin. Her PR için bir mantıksal değişiklik. Büyük belirtim PR'ları, bozan değişiklikleri gürültü içinde gizler.
• Açıklayıcı commit mesajları yazın. "İade isteğine refundReason ekle" mesajı "belirtimi güncelle" mesajından daha iyidir.
• Birleştirilmiş belirtimi asla doğrudan main üzerinde düzenlemeyin. Bir yazım hatası için bile her zaman dallandırın.

Sıkça Sorulan Sorular

Bir OpenAPI belirtimindeki bozan değişiklikleri nasıl tespit ederim?

CI'da, çekme isteğini main üzerindeki sürümle karşılaştıran bir belirtim fark aracı çalıştırın. oasdiff gibi araçlar her değişikliği bozan, bozan olmayan veya sınıflandırılmamış olarak sınıflandırır ve bozan bir değişiklik olduğunda derlemeyi başarısız edebilir. Bu, manuel incelemenin gözden kaçırabileceği kaldırılan alanları, yeni gerekli parametreleri ve değişen tipleri yakalar.

Tek bir OpenAPI dosyası mı tutmalıyım yoksa birçok dosyaya mı bölmeliyim?

Tek bir openapi.yaml ile başlayın. İncelemesi ve sürümlemesi en kolay olanıdır. Dosya büyüdüğünde veya birden çok ana sürümü paralel olarak sürdürdüğünüzde, ana sürüme göre (api-v1.yaml, api-v2.yaml) ayırın veya şemaları ayrı dosyalara bölmek için $ref kullanın. Erken bölmeyin; tek, okunabilir bir dosya, beş parçalanmış dosyadan daha iyidir.

Belirtimimi elle YAML yazmadan sürüm kontrolü yapabilir miyim?

Evet. Apidog'un Spec-First Modu, belirtimi görsel bir düzenleyicide düzenlemenize ve değişiklikleri Git'e çift yönlü olarak senkronize etmenize olanak tanır. Tutarlı YAML yazar, böylece farklarınız temiz ve çekme istekleriniz okunabilir kalır, aynı zamanda tam Git geçmişi ve incelemesini de elde edersiniz.