API Spesifikasyonunuzu Kod Olarak Ele Almak Ne Anlama Gelir?

API sözleşmeniz muhtemelen aynı anda üç yerde bulunuyor olabilir: Bir wikideki bir diyagram. Birinin geçen çeyrekte dışarı aktardığı bir Postman koleksiyonu. İki sürüm önce çalışan hizmetten farklılaşmış el yazısıyla yazılmış bir Markdown belgesi. Bu üçü çeliştiğinde ekibiniz tahminde bulunur. Tahminler entegrasyonları bozar.

API spesifikasyonunuzu kod olarak ele almak bunu düzeltir. Tek bir OpenAPI dosyası yazar, Git'e işler ve diğer kaynak dosyalar gibi incelersiniz. Bu tek dosyadan sahte sunucular, testler, belgeler ve SDK'lar oluşturursunuz. Spesifikasyon sonradan akla gelen bir şey olmaktan çıkar ve herkesin üzerinde çalıştığı sözleşme haline gelir.

Bu rehber, kod olarak spesifikasyonun ne anlama geldiğini, OpenAPI dosyasının neden uygulama kodunuzla aynı titizliği hak ettiğini ve araçlarınızla uğraşmadan iş akışını nasıl yöneteceğinizi açıklar.

Kod olarak spesifikasyon ne anlama geliyor?

Kod olarak spesifikasyon, API tanımınızın sürüm kontrolünde yaşayan düz metin bir dosya olduğu anlamına gelir. Bir veritabanı kaydı değil. Paylaşım bağlantılı barındırılan bir belge değil. `git diff` yapabileceğiniz, dallandırabileceğiniz ve birleştirebileceğiniz bir dosya.

Bu fikir doğrudan docs-as-code'dan (belgeyi kod olarak ele alma) ödünç alınmıştır; burada dokümantasyon, tanımladığı kodla aynı depoda yer alır ve aynı işlem hattından geçer. Kod olarak spesifikasyon, aynı disiplini API sözleşmesinin kendisine uygular. OpenAPI belgesi (YAML veya JSON) ana eserdir. Aşağı akıştaki diğer her şey ondan üretilir.

Bu değişim büyük bir sonuca yol açar. Spesifikasyon, tek gerçek kaynağı haline gelir. Bir geliştirici `/users/{id}`'nin ne döndürdüğünü bilmek istediğinde, eski bir wiki sayfasını değil, spesifikasyonu okur. Kalite Güvence bir test yazdığında, spesifikasyona göre doğrulama yapar. Bir iş ortağı entegrasyon yaptığında, spesifikasyondan oluşturulan bir SDK'yı çeker. Tek bir dosya, birçok çıktı.

Spesifikasyonu neden kod gibi ele almalıyız?

Spesifikasyon bir kez Git'te bir dosya olduğunda, kaynak kod için zaten güvendiğiniz her iş akışını devralırsınız.

Çekme isteklerinde inceleme. Bir uç noktadaki değişiklik, bir PR'da (çekme isteği) bir fark olarak görünür. İnceleyenler hangi alanların değiştiğini, hangi durum kodlarının eklendiğini ve bir yanıt şeklinin geriye dönük uyumluluğu bozup bozmadığını tam olarak görür. Bozucu bir değişiklik artık üretimde bir sürpriz değildir. Birleştirmeden önce bir yorum dizisidir. Bu, Git-tabanlı bir API iş akışının çekirdeğidir.

Fark dostu biçim. Düz YAML temiz bir şekilde farkları gösterir. Beş satırlık bir değişikliği saniyeler içinde okuyabilir ve anlayabilirsiniz. Bunu, "ne değiştiğinin" görünmez olduğu ikili bir dışa aktarma veya barındırılan bir araçla karşılaştırın. Spesifikasyon Git'te olduğunda, blame (suçlu bulma), geçmiş ve farklar hepsi sorunsuz çalışır.

Gerçek sürümleme. Her değişikliğin bir taahhüdü, bir yazarı ve bir zaman damgası vardır. Bir sürümü etiketleyebilir, bir `v2` yeniden tasarımı için dal oluşturabilir ve kötü bir değişikliği tek bir komutla geri alabilirsiniz. API geçmişiniz denetlenebilir hale gelir. Etiketleme ve dallanma stratejileri hakkında daha derinleşimli bilgi için, Git ile OpenAPI sürüm kontrolü bölümüne bakın.

Tek doğruluk kaynağı. Sahte sunucular, testler ve belgelerin hepsi aynı dosyadan türetildiği için bağımsız olarak sapma gösteremezler. Spesifikasyonu güncelleyin, yeniden oluşturun ve her çıktı tutarlı kalır.

İki yaklaşımın pratikte nasıl karşılaştırıldığı aşağıdadır.

OpenAPI ana eser olarak

OpenAPI, spesifikasyon için bariz bir formattır çünkü geniş çapta desteklenir ve makine tarafından okunabilir. Deponuzda tutacağınız küçük ama eksiksiz bir OpenAPI 3.1 dosyasının bir kısmı.

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. `Order`'a bir alan ekleyin, fark bir satır olur. `status` enum'ını değiştirin, bir inceleyici bunu anında görür. Servis kodunuzun yanında `api/openapi.yaml` altında tutun, spesifikasyon tanımladığı implementasyonla birlikte hareket eder.

Spesifikasyon ve belgeler

Tek bir kaynak dosyasının getirisi, ondan ürettiğiniz her şeydir.

Sahte sunucular. Bir sahte sunucuyu spesifikasyona yönlendirin ve tek bir uç nokta bile oluşturulmadan çalıştırılabilir bir API elde edin. Ön uç ve mobil ekipler, ilk günden itibaren sözleşmeye göre entegrasyon yapmaya başlar. Spesifikasyon değiştiğinde, sahte sunucu da onunla birlikte değişir.

Testler. Canlı hizmetin spesifikasyonla eşleştiğini doğrulayan sözleşme testleri oluşturun. Dağıtılan bir uç nokta, spesifikasyonda hiç bildirilmemiş bir alan döndürürse, test başarısız olur. Bu, sözleşme ile çalışan kod arasındaki sapmayı müşterilerden önce yakalar.

Belgeler. Spesifikasyonu otomatik olarak referans dokümantasyonuna dönüştürün. Artık kimse uç nokta tablolarını elle yazmıyor. Belgeler spesifikasyonla eşleşir çünkü onlar, spesifikasyonun render edilmiş halidir.

SDK'lar. Aynı dosyadan birden çok dilde istemci kütüphaneleri oluşturun. İş ortakları, her zaman güncel sözleşmeyi yansıtan tip güvenli bir SDK elde eder.

Her çıktı, spesifikasyonun bir fonksiyonudur. Girişi değiştirin, çıktıları yeniden oluşturun ve tutarlılık ücretsizdir.

Apidog, spesifikasyonu nasıl doğruluk kaynağı haline getiriyor?

Kod olarak spesifikasyonu elle çalıştırmak, bir CLI, bir sahte sunucu, bir belge oluşturucu ve bir Git kancasını bir araya getirmek anlamına gelir. Apidog bunu tek bir iş akışına dönüştürür.

Apidog'un Spec-First Modu, OpenAPI dosyanızı yetkili tanım olarak ele alır. Uç noktaları spesifikasyona göre tasarlarsınız ve Apidog, sahte sunucularınızı, testlerinizi ve dokümantasyonunuzu onunla senkronize tutar.

Bunu pratik hale getiren parça, çift yönlü Git senkronizasyonudur. Apidog, OpenAPI dosyanızı bir depodan okuyabilir ve değişiklikleri tekrar yazabilir, böylece Git'teki dosya ve Apidog'daki proje senkronize kalır. Daha hızlı olduğunda görsel olarak tasarım yapın, daha hızlı olduğunda YAML'yi doğrudan düzenleyin ve her iki yol da aynı işlenmiş dosyaya iner. Bu, ekip üyelerinize daha zengin bir düzenleyici sunarken PR inceleme akışınızı sağlam tutar. Spesifikasyon değişikliklerini yukarı akışa göndermenin mekaniği için, OpenAPI spesifikasyonunuzu GitHub ile nasıl senkronize edeceğinize bakın.

Sonuç: OpenAPI dosyası tek doğruluk kaynağı olarak kalır ve görsel araçlar onu değiştirmek yerine üzerinde yer alır.

Yaygın tuzaklar

Kod olarak spesifikasyon basittir, ancak bazı tuzaklar ekipleri erken dönemde yakalar.

Spesifikasyon ile uygulama arasındaki sapma. Spesifikasyonu yazmak yeterli değildir. Eğer çalışan hizmetin onunla eşleştiğini hiçbir şey kontrol etmezse, ikisi sessizce farklılaşır. CI'ya sözleşme testleri ekleyin, böylece bir uyumsuzluk müşteriyi değil, derlemeyi başarısız kılar.

Üretilmiş ile el yazısıyla yazılmış karışıklığı. Spesifikasyonun kod açıklamalarından mı üretildiğine yoksa kaynak olarak elle mi yazıldığına karar verin. İkisini karıştırmak, kimsenin hangi yarısının yetkili olduğunu bilmediği bir dosyaya yol açar. Tek bir yön seçin. Eğer spesifikasyon sizin doğruluk kaynağınızsa, kod açıklamalarını ona karşı kontrol ettiğiniz şey olarak ele alın, ikinci bir ana kopya olarak değil.

Spesifikasyonu bir sözleşme olarak değil, dokümantasyon olarak ele almak. Sadece okuduğunuz bir spesifikasyon bir belgedir. Ondan sahte sunucular, testler ve SDK'lar ürettiğiniz bir spesifikasyon bir sözleşmedir. Değer, dosyanın varlığından değil, çıktıları bağlamaktan gelir.

İncelemeyi atlamak. Git'te, inceleme olmadan birleşen bir spesifikasyon sadece Git'te bir dosyadır. Önemli olan çekme isteğidir. Kod için yaptığınız gibi spesifikasyon değişiklikleri için de bir inceleme isteyin.

Başlarken

Kod olarak spesifikasyonu kademeli olarak benimseyebilirsiniz.

1. Spesifikasyonunuzu kaydedin. OpenAPI dosyanızı `api/openapi.yaml` gibi bilinen bir yolda depoya taşıyın.
2. PR incelemesi isteyin. Spesifikasyon değişikliklerinin kodla aynı inceleme kapısından geçmesini sağlayın. Farklar sohbet konusu haline gelir.
3. Tek bir çıktı oluşturun. Sahte sunucular veya belgelerle başlayın. Dosya güncellendiğinde çıktının da güncellenmesi için spesifikasyonu bir oluşturucuya bağlayın.
4. Bir CI kontrolü ekleyin. Her PR'da spesifikasyonu lint edin. Birleşmeden önce geçersiz OpenAPI'yi yakalayın.
5. Sözleşme testleriyle döngüyü kapatın. Sahte sunucular ve belgeler akmaya başladığında, canlı hizmetin spesifikasyonla eşleştiğini doğrulayan testler ekleyin.

Her adım kendi başına değerlidir. Birinci adımda değer elde edersiniz ve her ekleme ile bu değeri katlarsınız.

Değişim, tanımlanması küçük ama etkisi büyüktür. Git'te, kod gibi incelenen, aşağı akıştaki her şeyi üreten tek bir dosya. Görsel düzenleme ve Git senkronizasyonunun yerleşik olarak gelmesini istiyorsanız, Apidog'un Spec-First Modunu deneyin ve OpenAPI dosyasının tek doğruluk kaynağınız olarak kalmasını sağlayın.

SSS

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

Aynı felsefeyi paylaşırlar: eseri sürüm kontrolünde tutun ve normal işlem hattınızdan gönderin. Belgeler kod olarak, bunu dokümantasyona uygular. Spesifikasyon kod olarak, bunu API sözleşmesinin kendisine uygular. Pratikte birbirlerini güçlendirirler, çünkü taahhüt edilmiş bir spesifikasyondan üretilen belgeler tanım gereği kod olarak belgelerdir.

Spesifikasyon dosyası hangi formatı kullanmalı?

YAML'deki OpenAPI yaygın bir tercihtir. YAML, çekme isteklerinde temiz farklar gösterir ve insanlar tarafından okunabilir, aynı zamanda sahte sunucular, testler ve SDK'lar oluşturmak için makine tarafından da ayrıştırılabilir. JSON da çalışır, ancak YAML genellikle daha düzenli farklar üretir.

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

CI'ya, çalışan hizmetin taahhüt edilmiş spesifikasyonla eşleştiğini doğrulayan sözleşme testleri ekleyin. Eğer bir uç nokta bildirilmemiş bir alan döndürürse veya belgelenmiş bir alanı çıkarırsa, derleme başarısız olur. Bu geri bildirim döngüsü, spesifikasyonu umut dolu bir belgeden uygulanabilir bir sözleşmeye dönüştüren şeydir.